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Abstract 



Obliq is a lexically-scoped untyped interpreted language that supports distributed object-oriented 
computation. An Obliq computation may involve multiple threads of control within an address space, 
multiple address spaces on a machine, heterogeneous machines over a local network, and multiple net- 
works over the Internet. Obliq objects have state and are local to a site. Obliq computations can roam 
over the network, while maintaining network connections. 
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1. Introduction 



Obliq is a lexically-scoped untyped interpreted language that supports distributed object-oriented 
computation. An Obliq computation may involve multiple threads of control within an address space, 
multiple address spaces on a machine, heterogeneous machines over a local network, and multiple net- 
works over the Internet. Obliq objects have state and are local to a site. Obliq computations can roam 
over the network, while maintaining network connections. 

1.1 Language Overview 

The guiding principle that separates Obliq from other distributed procedural languages is the ad- 
herence to lexical scoping in a distributed higher-order context. This principle is conceptually simple 
and has a number of interesting consequences: it supports a natural and consistent semantics of dis- 
tributed computation, and it enables elegant techniques for distributed programming. 

In lexically scoped languages, the binding location of every identifier is determined by simple 
analysis of the program text surrounding the identifier. Therefore, one can be sure of the meaning of 
program identifiers, and can much more easily reason about the behavior of programs. In a distributed 
language like Obliq, lexical scoping assumes a further role. It ensures that computations have a precise 
meaning even when they migrate over the network: a meaning that is determined by the binding loca- 
tion and network site of identifiers, and not by execution sites. 

Network-wide scoping becomes an issue in the presence of higher-order distributed computation, 
for example when remote sites acting as compute servers accept procedures for execution. The ques- 
tion here is: what happens to the free identifiers of network-transmitted procedures? Obliq takes the 
view that such identifiers are bound to their original locations, as prescribed by lexical scoping, even 
when these locations belong to different network sites. 

The principal way of structuring distributed computations in Obliq is through the notion of objects. 
Network services normally accept a variety of messages; it is then natural to see each service as a net- 
work object (or, more neutrally, as a network interface). Obliq supports objects in this spirit, relying for 
its implementation on Modula-3's network objects [Birrell, et al. 1993b]. 

The Obliq object primitives are designed to be simple and powerful, with a coherent relationship 
between their local and distributed semantics. Obliq objects are collections of named fields, with four 
basic operations: selection/invocation, updating/overriding, cloning, and delegation. There are no class 
hierarchies, nor complex method-lookup procedures. Every object is potentially and transparently a 
network object. An object may become accessible over the network either by the mediation of a name 
server, or simply by being used as the argument or result of a remote method. 

In any framework where objects are distributed across sites, it is critical to decide what to do about 
mobility and duplication of state. Normally, whenever a piece of data is transmitted from one site to 
another, it is implicitly copied. However, duplication of objects with state easily results in havoc, un- 
less the state is handled consistently across sites. 

To avoid problems with state duplication, objects in Obliq are local to a site and are never auto- 
matically copied over the network. In contrast, network references to objects can be transmitted from 
site to site without restrictions. An alternative approach would allow objects and their state to migrate 
from site to site, making sure that the integrity of their internal state is maintained during the act of mi- 
gration. We have chosen not to support migration directly, since it requires coordination across sites, 
and policy decisions about the optimal time of migration. However, atomic object migration can be 
coded from our primitives, specifically from cloning and delegation. 

In addition to the distribution of data, the distribution of computations must also be designed care- 
fully. It is clearly desirable to be able to transmit agents for remote execution. However, one should not 
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be satisfied with transmitting just the program text of such agents. Program text cannot carry with it 
live connections to its originating site, nor to any data or service at any other site. Hence the process of 
transmitting program text over the network implies a complete network disconnect from the current 
distributed computation. In addition, unpredictable dynamic scoping results from transmitting and then 
running program text containing free identifiers. 

Obliq computations, in the form of procedures or methods, can be freely transmitted over the net- 
work. Actual computations (closures, not source text) are transmitted; lexically scoped free identifiers 
retain their bindings to the originating sites. Through these free identifiers, migrating computations can 
maintain connections to objects and locations residing at various sites. Disconnected agents can be rep- 
resented as procedures with no free identifiers; these agents do not need to rely on prolonged network 
connectivity. 

In order to concentrate on distributed computation issues and to reduce complexity, Obliq is de- 
signed as an untyped language. This decision leads to simpler and smaller language processors that can 
be easily embedded in applications. Moreover, untyped programs are somewhat easier to distribute, be- 
cause we avoid problems of compatibility of types at multiple sites. 

The Obliq run-time is strongly typed: erroneous computations produce clean errors that are cor- 
rectly propagated across sites. The run-time data space is heterogeneous, meaning that there are differ- 
ent kinds of run-time values and no provisions to discriminate between them; heterogeneity discour- 
ages writing programs that would be difficult to typecheck in typed languages. Because of heterogene- 
ity and lexical scoping, Obliq is in principle suitable for static typing. More importantly, Obliq is com- 
patible with the disciplined approach to programming that is inspired by statically typed languages. 

Lexical scoping has many interesting implications in a distributed context. One is that, together 
with strong run-time typing and interpreted execution, it can provide network security guarantees. 
Consider the situation of a server executing incoming foreign agents. Because of lexical scoping, these 
agents have access only to the data and resources that they can reference via free variables or that they 
explicitly receive in the form of procedure parameters. In particular, foreign agents cannot access data 
or resources at the server site that are not explicitly given to them. For example, operations on files in 
Obliq require file system handles that are available as global lexically bound identifiers at each site. A 
foreign agent can operate on the file system handle of its originating site, simply by referring to it as a 
free identifier. But the file system handle at the server site is outside its lexical scope, and hence unob- 
tainable except with the cooperation of the server. Degrees of file protection can be represented by file 
system handles with special access rights. 

1.2 Distributed Semantics 

The Obliq distributed semantics is based on the notions of sites, locations, values, and threads. 

Sites (that is, address spaces) contain locations, and locations contain values. Each location be- 
longs to a unique site. We often talk about a local site, in relative terms, and about remote sites, mean- 
ing any site other than the local site. Sites are not explicit in the syntax but are implicit in operations 
that produce new locations. 

Threads are virtual sequential instruction processors. Multiple threads may be executed concur- 
rently, both at the same site or at different sites. A given thread may stop executing at a site, and con- 
tinue executing at another site. That is, threads may jump from site to site while retaining their concep- 
tual identity. The current site is where execution of a given thread of control takes place at a given 
moment. 

In the Obliq syntax, constant identifiers denote values, while variable identifiers denote locations. 
A location containing a value may be updated by assignment to the variable denoting the location. 

Obliq values include basic values (such as strings or integers), objects, arrays, closures (the results 
of evaluating methods or procedures), and other values that we need not discuss at this point. 



Page 2 



A value may contain embedded locations. An array value has embedded locations for its elements, 
which can be updated. An object value has embedded locations for its fields and methods, which can 
be updated and overridden. A closure value may have embedded locations because of free variables in 
its program text that refer to locations in the surrounding lexical scope. Basic values do not contain 
embedded locations. When a location is created during a computation, it is allocated at the current site. 

Values may be transmitted over the network. A value containing no embedded locations is copied 
on transmission. Embedded locations are automatically replaced by network references, so that the ac- 
tual locations do not move from the site where they are originally allocated. An Obliq value may con- 
tain network references to locations at different sites. In particular, a closure value may contain pro- 
gram text that, when executed, accesses data (bound to its free identifiers) over the network. 

Every Obliq object consists of a collection of locations spanning a single site; hence the object it- 
self is bound to a unique site 1 . This immobility of objects is not a strong limitation, because objects can 
be cloned to different sites, and because procedures can be transmitted that allocate objects at different 
sites. Hence, a collection of interacting objects can be dynamically allocated throughout the network, 
but not moved afterwards. If migration is necessary, cloning can be used to provide the needed state 
duplication, and delegation can be used to redirect operations to the clones. 

We have stressed so far how Obliq computations can evolve into webs of network references. 
However, this is not necessarily the case. For example, a procedure with no free identifiers forms a 
completely self-contained computing agent. The execution of these agents may be carried out au- 
tonomously by remote compute servers (the agents may dynamically reconnect to report results). In- 
termediate situations are also possible, as with semi-autonomous agents that maintain low-traffic teth- 
ers to their originating site. 

In conclusion, the distributed semantics of Obliq is defined so that data and computations are net- 
work-transparent: their meaning does not depend on allocation sites or execution sites (of course, com- 
putations may receive different arguments at different sites). At the same time, Obliq programs are 
network-aware: distribution is achieved by explicit acts that give full control on communication pat- 
terns. 

Lexical scoping makes it easy to distribute computations over multiple sites, since computations 
behave correctly even when they are carried out at the wrong place (by some measure). Flexibility in 
distribution can, however, result in undesirable network traffic. Obliq relieves some of the burden of 
distributing data and computations, but care and planning are still required to achieve satisfactory dis- 
tributed performance. 

2. Local Objects 

In this section we discuss the Obliq object primitives in the context of a single execution site. 
These primitives are then reinterpreted in the next section and given distributed meaning. 

2.1 Objects and their Fields 

An Obliq object is a collection of fields containing methods, aliases, or other values. A field con- 
taining a method is called a method field. A field containing an alias is called an alias field. A field 
containing any other kind of values, including procedure values, is called a (proper) value field. Each 
field is identified by a field name. Syntactically, an object has the form: 

{x 1 => a lr ... , x n => a n } 



1 In the implementation, network references are generated to objects and arrays, not to each of their embedded locations. 
However, it is consistent and significantly simpler to carry out our discussions in terms of network references to locations. 
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where n>0, and r x ± n are distinct field names. (There is no lexical distinction between field names and 
program identifiers.) The terms r a i "' are siblings of each other, and the object is their host object. Each 
r a ± n can be any term, including a method, or an alias. 
A value field is, for example: 

x => 3 

A method field has the form: 

x => meth(y,y 1 , ... ,y n ) b end 

Here, the first parameter, r y n , denotes self: the method's host object. The other parameters, for n>0, are 
supplied during method invocation. The body of the method is the term V, which computes the result 
of an invocation of r x n . 

An alias field contains an alias: 

x => alias y of b end 

Operations on the r x n field of this object are redirected to the r y n field of the object r b n . The precise ef- 
fect is explained case by case in the next section. 

Methods and procedures are supported as distinct concepts. Procedures start with the keyword 
proc 1 instead of r meth n and have otherwise the same syntax. The main differences between the two 
are as follows. Methods can be manipulated as values but can be activated only when contained in ob- 
jects, since self needs to be bound to the host object. In contrast, procedures can be activated by normal 
procedure call. Further, a procedure can be inserted in an object field and later recovered, while any 
attempt to extract a method from an object results in its activation. 

Obliq methods are stored directly in objects, not indirectly in object classes or prototypes. Method 
lookup is a one-step process that searches a method by name within a single object. There is no class or 
delegation hierarchy to be searched iteratively, and there is no notion of super. Inheritance is obtained 
by cloning methods from other objects. Method lookup is implemented by a nearly constant-time 
caching technique, with independent caches for each operation instance, that does not penalize large 
objects, . 

There are no provisions in Obliq for private fields or methods, but these can be easily simulated by 
lexical scoping. For example, r (var x=3; { ... } ) is an expression setting up a local variable 
r x n and returning an object that has r x n in its scope. Since the scope of r x n is limited by the parentheses, 
no other part of the program can access r x n . In addition, aliases can be used to create views of objects 
that omit certain fields or methods. 

2.2 Object Operations 

Apart from object creation, there are four basic operations on objects: selection/invocation, updat- 
ing/overriding, cloning, and delegation. Field aliasing affects the semantics of all of them, as described 
below case by case. 

Selection (and Invocation) 

This operation has two variants for value selection and method invocation: 

a . x 

a.x(b lf ... ,b n ) 

The first form selects a value from the field r x n of r a n and returns it. The second form invokes a method 
from the field r x n of r a n , supplying parameters, and returning the result produced by the method; the ob- 
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ject V is bound to the self parameter of the method. For convenience, the first form can be used for in- 
vocation of methods with no parameters. 

If the field r x n of r a n , above, is an alias for r x x n of r a 1 n , then r a . x n behaves like r a x . x x n , and 
r a . x (b lr ... , b n ) n behaves like r a 1 .x 1 (b 1 , ... , b n ) \ If the field r x 1 ' of r a x n is itself an alias, 
the process continues recursively. 

Updating (and Overriding) 

This operation deals with both field update and method override: 

a . x : =b 

Here the field r x n of V is updated with a new value V. If V contains a method and V is a method, we 
have method override. If r x n and V are ordinary values, we have field update. The other two possibili- 
ties are also allowed: a field can be turned into a method (of zero arguments), and vice versa. 

However, if the field r x n of V is an alias for r x 1 1 of r a{, then r a . x : =b n behaves like r a 1 . x 1 : =b\ 
and so on recursively. 

Cloning 

The third operation is object cloning, generalized to multiple objects: 

clone (a) 

clone (a lr ... , a n ) 

In the case of a single argument, a new object is created with the same field names as the argument 
object; the respective locations are initialized to the values, methods, or aliases of the argument object. 
Note that this operation cannot be simulated by hand, because any attempt to extract the methods or 
aliases of an object activates them. 

In the case of multiple arguments, a single object is produced that contains the values, methods, 
and aliases of all the argument objects (an error is given if there are field name conflicts). Useful situa- 
tions are 'clone (a, {...}) n , where we inherit the fields of r a n , and add new fields, and 
"clone ( a 1 , a 2 ) \ where we multiply inherit from r a x n and r a 2 ". 

It is common for the parameters of "clone" to be prototypes (or classes): by convention, proto- 
types are objects that are meant only as repositories for methods and initial values. Via cloning, proto- 
types act as object generators; cloning a prototype corresponds to newing an object. 

A partial prototype (or mixin, or abstract class) is a prototype whose methods refer through self to 
fields not in the prototype. Obviously, a partial prototype should never be used as an object or an object 
generator. However, one can clone partial prototypes together to obtain complete working objects. 

Cloning can also be applied to objects used in computations. In particular, self can be cloned. 

Delegation 

Our final operation is delegation, which is the replacement of fields with aliases. In section 2.1 we 
have seen how to initialize alias fields: 

{ x => alias y of b end, ... } 

Moreover, it is possible to assign aliases to fields of existing objects with the following delegation op- 
eration (the syntax is similar to update, but this is really a separate operation): 

a.x := alias y of b end 
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Any further operation on V of V is redirected to r y n of V. However, delegation replaces fields with 
aliases regardless of whether those fields are already aliased; updating r x n of "a 1 again with another alias 
causes r x n of "a 1 (not r y n of V) to be updated. 

A special delegation construct can be used to delegate whole objects at once: 

delegate a 1 to a 2 end 

The effect is to replace every field r x L " of r a 1 "' (including alias fields) with "alias x ± of a 2 end". 
Cloning can be used to assemble compound delegate objects. 

Aliases and delegation must be used very carefully and, in most circumstances, are best avoided. 
However, delegation is already implicit in the notion of local surrogate of a remote object: we have 
simply lifted this mechanism to the language level. By doing this, we are able to put network delega- 
tion under flexible program control, as shown later in the case of object migration. 



2.3 Simple Examples 

Let us examine some simple examples, just to became familiar with the Obliq syntax and seman- 
tics. More advanced examples are presented in sections 4 and 5. 

The following object has a single method that invokes itself through self (the "s 1 parameter). A 
"let 1 declaration binds the object to the identifier V: 

let o = 

{ x => meth(s) s.x() end } ; 

An invocation of r o . x ( ) 1 results in a divergent computation. Divergence is obtained here without any 
explicit use of recursion: the self-application implicit in method invocation is sufficient. 

The object below has three components. (1) A value field r x n . (2) A method r inc n that increments 
r x n through self, and returns self. (3) A method next 1 that invokes "inc 1 through self, and returns the 
r x n component of the result. 

let o = 
{ x => 3, 

inc => meth(s,y) s.x := s.x+y; s end, 
next => meth(s) s.inc(l) .x end } ; 

Here are some of the operations that can be performed on V: 

o . x Selecting the r x n component, producing 3. 

o . x : = 0 Setting the r x n component to zero, 
o . inc ( 1 ) Invoking a method, with parameters. 

o . next ( ) Invoking a method with no parameters (o . next is also valid), 
o.next := meth(s) clone (s) .inc(l) .x end 

Overriding "next 1 so that it no longer modifies its host object. 



3. Remote Objects 

In this section we revisit the Obliq primitives in the context of objects that are distributed over 
multiple sites. We discuss distributed state in general, including arrays and variables. 
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3.1 State 



State is local in the sense that every location is forever bound to a site. At the same time, state is 
distributed, in the sense that there are many communicating sites. Every location at every site can po- 
tentially be accessed and modified over the network. Moreover, values may contain embedded loca- 
tions belonging to current site or, via network aliases, to remote sites. Access and update of a remote 
location involves network communication, but is otherwise handled transparently in the same manner 
as access and update of a local location. 

There are three kinds of entities in Obliq that directly contain locations, and hence have state: 

objects: {x 1 => a lf ... ,x n => a n } 
every field of an object has state 
access: a . x, 
update: a . x : = b, 

arrays: [a lr ... , a n ] 

every element of an array has state 
access: a [ n ] 
update: a [ n ] : = b 

variables: var x = a 

variables have state (identifiers declared by r let n do not) 
access: x 
update: x : = b 

When objects, arrays, and variables are created during a computation, their locations are allocated 
at the current site. 

3.2 Transmission 

As discussed in the introduction, the state (i.e. set of locations) associated with objects, arrays, and 
variables is never duplicated or transmitted over the network. Network references to locations, how- 
ever, are free to travel. Every attempted transmission of a location over the network is, in effect, inter- 
cepted and replaced by the transmission of a network reference to that location. Remote operations on 
these network references are reflected back to the original locations, as described in section 3.3. 

Stateless values, unlike locations, are copied when transmitted over the network. Structures that 
are copied include basic data types and the internal representations of program text. 

In the general case of transmission we may have a mixed situation, with a few layers of stateless 
data structures that end up referring to location. These data structures with embedded locations are 
copied up to the point where they refer to locations; then network references are generated. 

A critical issue is the transmission of closures, which are the values resulting from the evaluation 
of procedures and methods. A closure consists of two parts: (1) the internal representation of the source 
text of a method or procedure, and (2) a table associating free identifiers in the source text to their val- 
ues in the lexical scope of evaluation. 

The free-identifiers table within a closure may refer to variables and to values with embedded lo- 
cations. The general rule for transmitting structures with embedded locations applies to closures; hence 
closures are copied up to the locations embedded in their free-identifier tables. 

For example, consider the following Obliq code, declaring a variable r x n initialized to r Cf, and a 
procedure r p n whose body refers to r x n (that is, has r x n as a free identifier): 



a.x(a lf ... ,a n ) 
delegate a to b end 
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var x = 0; 

let p = proc () x := x+1 end; 

Suppose that, after the execution of the first line, the variable r x n is bound to the location loc 0 , rela- 
tive to the current site s 0 . Then, after the execution of the second line, the identifier r p n is bound to the 
closure: 

"proc() x := x+1 end" where x = loc 0 

where "proc... end" represents the internal representation of program code, and the free identifier 
table is shown following where. 

Upon transmission to a site s b the location loc 0 is replaced by a network reference <s 0 ,loc 0 > to that 
location; therefore site s [ receives the data structure 2 : 

"proc () x := x+1 end" where x = <s 0 ,loc 0 > 

In general terms, a closure is a pair consisting of a piece of source text and a pointer to an evalua- 
tion stack. Transmission of a closure, in this view, implies transmission of an entire evaluation stack. 
The implementation of closures described above (which is well-known for higher-order languages) has 
the effect of reducing network traffic, by transmitting only the values from the evaluation stack that 
may be needed by the closure. This optimization is enabled by lexical scoping 

3.3 Distributed Computation 

We now reinterpret the semantics of operations on objects in the case of remote objects. In pass- 
ing, we comment on the semantics of remote arrays and variables. 

Selection (and Invocation) 

When a value field of a remote object is selected, its value is transmitted over the network (as dis- 
cussed in section 3.2) to the site of the selection. 

The extraction of a remote array element and the access of a remote variable work similarly. 

When a method of a remote object is invoked, the arguments are transmitted over the network to 
the remote site, the result is computed remotely, and the final value (or error, or exception) is returned 
to the site of the invocation. 

It is interesting to compare the invocation of a remote method with the invocation of a procedure 
stored in the value field of a remote object. In the first case, the computation is remote, as described 
above. In the second case, the procedure is first transmitted from the remote object to the local site, by 
the semantics of field selection, and then executed locally. 

Updating (and Overriding) 

When a field of a remote object is updated, or when a method is overridden, a value is transmitted 
over the network and installed into the remote object. Field update may involve the transmission of a 
procedure closure, and method override involves the transmission of a method closure. 

The update of a remote array element and the assignment of a remote variable work similarly. 

Cloning 

When a collection of remote or local objects is cloned, the clone is created at the local site. Its con- 
tents (including method closures) may have to be fetched over the network. 



In the implementation, loc 0 is a Modula-3 network object with access and update methods. 
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The extraction of remote subarrays and the concatenation of remote arrays work similarly. 
Delegation 

In the case where the object being delegated is remote, the remote fields are replaced by the ap- 
propriate aliases. In the case where the other object is remote, aliases are generated to it. 

Aliases 

A local object field aliased to a remote object behaves as the field of the remote object, as de- 
scribed in this section case by case. 

3.4 Self-inflicted Operations 

The four basic object operations can be performed either as external operations on an object, or as 
internal operations through self. This distinction is useful in the contexts of object protection and serial- 
ization, discussed in the next two sections. 

When a method operates on an object other than the method's host object, we say that the opera- 
tion is external to the object. By contrast, when a method operates directly on its own self we say that 
the operation is self-inflicted: 

If r op" is either a select, update, clone, or delegate operation, 
then r op(of is self-inflicted 

iff r o n is the same object as the self of the current method (if any). 
Moreover, r op{ of is external iff it is not self-inflicted. 

Here, by the current method we mean the last method that was invoked in the current thread of control 
and that has not yet returned. Procedure calls do not change or mask the current method, even when 
they have not yet returned. 

Whether an operation is self-inflicted can be determined by a simple run-time test. Consider, for 
example the object: 

{ p => meth(s) s.q.x end, q => ... } 

Here the operation r s . q is self-inflicted, since r s n is self. But the r . x n operation in r s . q . x n is self-in- 
flicted depending on whether r s . q returns self; in general this can be determined only at run-time. 

If we replace r s . q n with a procedure call r p ( s ) n which simply performs r s . q\ then r s . q n is still 
self-inflicted, and r p ( s ) . x n may still be. The notion of "self for self-inflicted operations is preserved 
through procedure calls, but not through external method invocations or thread creation. 

3.5 Protected Objects 

It is useful to protect objects against certain external operations, to safeguard their internal invari- 
ants. Protection is particularly important, for example, to prevent clients from overriding methods of 
network services, or from cloning servers. Still, protected objects should be allowed to modify their 
own state and to clone themselves. 

This is where the notion of self-inflicted operations first becomes useful. A protected object is an 
object that rejects external update, cloning, and delegation operations, but that admits such operations 
when they are self-inflicted. Objects can be declared protected, as shown below: 

{ protected, x 1 => a lf ... , x n => a n } 
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Therefore, for example, methods of a protected object can update sibling fields through self, but exter- 
nal operations cannot modify such fields. 

Note that a protection mechanism based on individual "private" fields would not address protec- 
tion against cloning and delegation. 

3.6 Serialized Objects 

An Obliq server object can be accessed concurrently by multiple remote client threads. Moreover, 
local concurrent threads may be created explicitly. To prevent race conditions, it must be possible to 
serialize access to objects and other entities with state. 

We say that an object is serialized when (1) in presence of multiple threads, at most one method of 
the object can be executing at any given time, but still (2) a method may call a sibling through self 
without deadlock. Note that requirement (2) does not contradict invariant (1), because an invocation 
through self suspends a method before activating a sibling. 

The obvious approach to implementing serialized objects, adopted by many concurrent languages 
is to associate mutexes with objects (for example, see [Bal, Kaashoek, Tanenbaum 1992]). Such mu- 
texes are locked when a method of an object is invoked, and unlocked when the method returns, guar- 
anteeing condition (1). This way, however, we have a deadlock whenever a method calls a sibling, vio- 
lating condition (2). We find this behavior unacceptable because it causes innocent programs to dead- 
lock without good reason. In particular, an object that works well sequentially may suddenly deadlock 
when a mutex is added. ([Brewer, Waldspurger 1992] gives an overview of previous solutions to this 
problem.) 

A way to satisfy condition (2) is to use reentrant mutexes, that is, mutexes that do not deadlock 
when re-locked by the "same" thread (for example, see [Forte 1994]). On one hand, this solution is too 
liberal, because it allows a method to call an arbitrary method of a different object, which then can call 
back a method of the present object without deadlocking. This goes well beyond our simple desire that 
a method should be allowed to call its siblings: it may make objects vulnerable to unexpected activa- 
tions of their own methods, when other methods have not yet finished reestablishing the object's in- 
variants. On the other hand, this solution may also be too restrictive because the notion of "same" 
thread is normally restricted to an address space. If we want to consider control threads as extending 
across sites, then an implementation of reentrant locks might not behave appropriately. 

We solve this dilemma by adopting an intermediate locking strategy, which we call self serializa- 
tion, based on the notion of self-inflicted operations described in section 3.4. 

Serialized objects have an implicit associated mutex, called the object mutex. An object mutex se- 
rializes the execution of selection, update, cloning, and delegation operations on its host object. Here 
are the simple rules of acquisition of these object mutexes: 

• External operations always acquire the mutex of an object, and release it on completion. 

• Self-inflicted operations never acquire the mutex of their object. 

Note that a self-inflicted operation can happen only after the activation of an external operation on the 
object that is executed by the same thread. The external operation has therefore already acquired the 
mutex. 

The serialization attribute of an object is specified as follows: 

{ serialized, x x => a x , ... , x n => a n } 

With self-serialization, a method can modify the state of its host object and can invoke siblings without 
deadlocking. A deadlock still occurs if, for example, a method invokes a method of a different object 
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that then attempts an operation on the original serialized object. A deadlock occurs also if a method 
forks an invocation of a sibling and waits on the result. 

Our form of object serialization solves common mutual exclusion problems, for example for net- 
work servers maintaining some simple internal state. More complex situations require both sophisti- 
cated uses of explicit mutexes, and conditional synchronization (where threads wait on conditions in 
addition to mutexes). Because of these more complex situations, Obliq supports the full spectrum of 
Modula-3 threads primitives [Birrell 1991; Horning, et al. 1993]; some through an external interface, 
and some directly in the syntax. 

Conditional synchronization can be used also with the implicit object mutexes. A new condition r c 
can be created by "condition ( ) 1 and signaled by "signal ( c) \ A special watch 1 statement al- 
lows waiting on a condition in conjunction with the implicit mutex of an object. This statement must be 
used inside the methods of a serialized object; hence, it is always evaluated with the object mutex 
locked: 

watch c until guard end 

The watch 1 statement evaluates the condition, and, if "guard evaluates to true, terminates leaving 
the mutex locked. If the guard is false, the object mutex is unlocked (so that other methods of the ob- 
ject can execute) and the thread waits for the condition to be signaled. When the condition is signaled, 
the object mutex is locked and the boolean guard is evaluated again, repeating the process. See section 
5.1 for an example. 

Objects with implicit mutexes can be cloned: a fresh implicit mutex is created for the clone. Re- 
mote objects with implicit mutexes can also be cloned: a fresh implicit mutex is generated at the 
cloning site. Note, however, that an error is reported on any attempt to transmit an explicit mutex (or 
thread, or condition) between different sites, since these values are strongly site-dependent. 

Consider the case of threads blocked on a condition within an object that is cloned. For local 
cloning, a fresh implicit mutex is created for the clone, with no threads blocked on it. The condition, 
however, is shared between the two objects. For remote cloning, since the watch statement refers to a 
condition and conditions cannot be transmitted, then the method closure that contains the watch state- 
ment cannot be transmitted, and hence the remote cloning fails. 

Consider now the case of threads blocked on a condition within a method that is overridden or del- 
egated. When the thread resumes, the original method runs to completion with a modified self. Thus, a 
blocked thread must deal with the fact that the self may change in non-trivial ways: this is specially in- 
sidious if the object is serialized but not protected. 

Unlike objects, there is no automatic serialization for variables or arrays. If necessary, their access 
can be controlled through serialized objects or explicit mutexes. Even for objects, serialization is nei- 
ther compulsory nor a default, since its use is not always desirable. In some cases it may be sufficient 
to serialize server objects (the concurrent entry points to a site) and leave all other objects unserialized. 

3.7 Name Servers 

Obliq values can flow freely from site to site along communication channels. But such channels 
must first be established by interaction with a name server. A name server for Obliq programs is an ex- 
ternal process that is uniquely identified by its IP address; it simply maintains a table associating text 
strings with network references [Birrell, et al. 1994]. 

The connection protocol between two Obliq sites is as follows. The first site registers a local, or 
remote, object under a certain name with a known name server. The second site asks the name server 
for (the network reference to) the object registered under that name. At this point the second site ac- 
quires a direct network reference to the object living in the first site. The name server is no longer in- 
volved in any way, except that it still holds the network reference. Obliq values and network references 
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can now flow along the direct connection between the two sites, without having to be registered with a 
name server. 

This protocol is coded as follows, using the built-in net 1 module. An Obliq object can be ex- 
ported to a name server by the command: 

Sitel: net_export ( "ob j " , NameServer, sitelObj) 




Sitel 



where r "ob j 1,1 is the registration name for the object, "sitelObj 1 is the object, and 'NameServer 
is a string containing the net IP address or IP name of the machine running the desired name server. 
(The empty string can be used as an abbreviation for the local IP address.) The object is now available 
through the name server, as long as the site that exports it is alive. Objects and engines (section 3.8) are 
the only Obliq values that can be exported to name servers. 

Any other site can then import a network reference to the object: 

Site2: let sitelObj = net_import ( "ob j " , NameServer) 




Sitel Site2 

Object operations can be applied to "sitelObj 1 as if it were a local object, as discussed in section 3.3. 

The two sites can now communicate directly; the name server is out of the loop. (It may be told to 
forget the object by redefining its registration name.) 

Site2: sitelObj . op (args) 




Sitel ^ ^ Site2 

TCP 



Finally, the object may be made available to a third site by transmitting it through an established 
communication channel: 

Site2: site30bj . op (sitelObj ) 
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Sitel 



Site2 Site3 



Objects are garbage collected at a site when they are no longer referred to, either locally or via network 
references [Birrell, etal. 1993a]. 

Another name service operation returns status information about a network reference, as a text 
string. It can be used to "ping" a remote object without affecting it: 

net_who ( site 10b j ) ; 

Communication failures raise an exception ( r net_f ailure 1 ), which can be trapped. These fail- 
ures may mean that one of the machines involved has crashed, or that an Obliq address space was ter- 
minated. There is no automatic recovery from network failures. 

3.8 Execution Engines 

We shall see soon that compute servers are definable via simple network objects. However, com- 
pute servers are so common and useful that we provide them as primitives, calling them execution en- 
gines. An execution engine accepts Obliq procedures (that is, procedure closures) from the network and 
executes them at the engine site. An engine can be exported from a site via the primitive: 

net_exportEngine ( "EnginelSSitel " , NameServer, arg) ; 

The 'arg 1 parameter is supplied to all the client procedures received by the engine. Multiple engines 
can be exported from the same site under different names. 

A client may import an engine and then specify a procedure to be execute remotely. An engine 
value behaves like a procedure of one argument: 

let atSitel = 

net_importEngine ( "EnginelSSitel" , NameServer) ; 

atSitel (proc (arg) 3+2 end); 

Implementing engines as remote procedures, instead of a remote objects, allows self-inflicted op- 
erations to extend across sites; this turns out to be important for object migration. 

4. Local Techniques 

In this section we discuss a collection of single- threaded examples to illustrate Obliq' s sequential 
features. A collection of concurrent and distributed examples is given in section 5; the impatient reader 
may want to skip forward. In both these sections the emphasis is on advanced, rather than tutorial, ex- 
amples. 

4.1 Recursion and Iteration 

We start with a simple example, to illustrate the use of definitions, local variables, and control 
constructs. The factorial function is defined in recursive and iterative style. 



Page 13 



let rec recFact = 
proc (n) 

if n is 0 then 1 else n * recFact(n-l) end; 
end; 

let itFact = 
proc (n) 
var cnt 
loop 

if cnt 
acc : = 
end; 
acc; 
end; 

Identifiers are declared by "let 1 , and updatable variables by var 1 . Recursive definitions are obtained 
by r let rec". The identity predicate is called r i s 1 . A sequence of statements separated by semicolons 
returns the value of the last statement; hence the iterative factorial program returns r acc. 

4.2 The Object-Oriented Numerals 

This next example illustrates the expressive power of the object primitives by encoding the natural 
numbers purely in terms of objects. 

let zero = 
{case => 

proc(pz,ps) pz() end, 
succ => 

meth (self) 

let o = clone (self); 

o.case := proc(pz,ps) ps(self) end; 

o 

end } ; 

The numeral 'zero 1 has two fields. The r succ field produces successive numerals by appropriately 
modifying the current numeral. The "case 1 field is used to discriminate on zero: the idiom 
r (n.case) (proc () b end, proc(p) c end) 1 is read, informally, as "if n is zero then return 
b, else bind the predecessor of n to p and return c". 

The code of the "succ 1 method depends heavily on Obliq peculiarities: it clones self, and embeds 
the current self into a procedure closure, so that it can be used later. For example, the numeral "one 1 , 
computed as, r zero . succ ( ) \ is: 

{case => proc(pz,ps) ps(zero) end, 
succ => (as for zero) } 

Hence, r one . case (pz, ps ) 1 correctly applies r ps n to the predecessor of "one 1 . 



= n; var acc = 1; 

is 0 then exit end; 
: cnt * acc; cnt := cnt - 1 ; 
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To show that the encoding is fully general, we define the successor, predecessor, and test for zero 
procedures: 

let succ = 

proc (n) n.succ end; 

let pred = 
proc (n) 

(n.case) (proc () zero end, proc(p) p end) 
end; 

let iszero = 
proc (n) 

(n.case) (proc () true end, proc(p) false end) 
end; 

4.3 The Prime Numbers Sieve 

This example shows an interesting case of methods overriding themselves, and of objects replicat- 
ing themselves by cloning. The program below prints the prime numbers when the method r m n of the 
'sieve 1 object is invoked with successive integers starting from 2. Each time a new prime p is found, 
the sieve object clones itself into two objects. One of the clones then transforms itself into a filter for 
multiples of p; non-multiples are passed to the other clone. 

let sieve = 
{ m => 

meth(s, n) 

print (n) ; (* defined elsewhere *) 

let sO = clone ( s ) ; 
s . m : = 

meth (si, nl) 

if (nl % n) is 0 then ok else sO.m(nl) end 

end; 

end 

}; 

(* print the primes < 100 *) 

for i = 2 to 100 do sieve. m(i) end; 

At any point in time, if n primes have been printed, then there exists n filter objects plus a clone of the 
original sieve object. 

4.4 A Calculator 

This example illustrates method overriding, used here to store the "pending operations" of a pocket 
calculator. 
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let calc = 

{ arg => 0.0, 
acc => 0.0, 

enter => 
meth ( s , n) 
s . arg : = 

s 

end, 

add => 
meth ( s ) 
s . acc : = 
s . equals 
s 

end, 

sub => 
meth ( s ) 
s . acc : = 
s . equals 
s 

end, 
equals => 



(* 
(* 



the "visible" argument display *) 
the "hidden" accumulator *) 

entering a new argument *) 



n; 



(* the addition button *) 
s . equals; 

:= meth(s) s.acc+s.arg end; 



(* the subtraction button *) 
s . equals; 

:= meth(s) s.acc-s.arg end; 



(* the result button (and operator stack) 



meth(s) s . arg end, 

reset => (* the reset button *) 

meth ( s ) 

s . arg : =0 . 0 ; 
s . acc : =0 . 0 ; 

s . equals : =meth ( s ) s.arg end; 
s 



end 



}; 

For example: 



calc 


. reset 


. enter ( 3 . 


• 5) 


. equals ; 


(* 


3 . 


.5 


*) 


calc 


. reset 


. enter ( 3 . 


■ 5) 


.sub .enter(2.0) .equals; 


(* 


1 . 


.5 


*) 


calc 


. reset 


. enter ( 3 . 


■ 5) 


. equals ; 


(* 


3 . 


.5 


*) 


calc 


. reset 


. enter ( 3 . 


• 5) 


.add .equals; 


(* 


7 . 


.0 


*) 


calc 


. reset 


. enter ( 3 . 


.5) 


.add .add .equals; 


(* 


10 . 


.5 


*) 
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4.5 Surrogates 

Here we create a non-trivial surrogate for the calculator object of section 4.4. Unlike the original 
calculator, this object is protected against outside interference. Some of the calculator fields are shared 
by aliasing, some are hidden, some are renamed, and one is added. 

let publicCalc = 
{ protected, 

enter => alias enter of calc end, 

pi => meth(s) s .enter (3 . 1415926535897932384626433833) end, 
plus => alias add of calc end, 
minus => alias sub of calc end, 
equals => alias equals of calc end, 
reset => alias reset of calc end } 

5. Distributed Techniques 

In this section we code some distributed programming techniques in Obliq. Each example is typi- 
cal of a separate class of distributed programs, and illustrates the unique features of Obliq. 

5.1 A Serialized Queue 

We begin with an example of ordinary concurrent programming to illustrate the threads primitives 
that are used in the sequel. We implement a queue that can be accessed consistently by concurrent 
reader and writer threads. 

The queue is implemented as a serialized object with 'read 1 and r write n methods. These meth- 
ods refer to free identifiers that are hidden from users of the queue. The object mutex is used, implic- 
itly, to protect a private variable that contains an array of queue elements. Another private variable 
contains a condition r nonEmpty n used for signaling the state of the queue. 

The write method adds an element to the queue, and signals the non-empty condition, so that at 
least one reader thread waiting on that condition wakes up (a similar broadcast operation wakes up all 
waiting threads). The object mutex is locked throughout the execution of the write method, therefore 
excluding other writer or reader threads. 

When a read method starts executing, the object mutex is locked. Its first instruction is to watch for 
the non-empty condition, and for the existence of elements in the queue. If the queue is non-empty, the 
reader simply goes ahead and removes one element from the queue. If the queue is empty, the reader 
thread is suspended and the object mutex is released (allowing other reader and writer threads to exe- 
cute). The reader is suspended until it receives a signal for the non-empty condition; then the object 
mutex is locked, and the reader thread proceeds as above (possibly being suspended again if some 
other reader thread has already emptied the queue). 

What is important here is that a reader thread may be blocked inside a method, and yet a writer 
thread can get access and eventually allow the first thread to proceed. Hence, even though only one 
thread at a time can run, multiple threads may be simultaneously present "in" the object. 

Here, r [ ... ] 1 is an array, r # n is array-size, and r @ n is array-concatenation. 
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let queue = 

(let nonEmpty 
var q = [ ] ; 



condition ( ) 



(* the (hidden) queue data *) 



{protected, serialized, 
write => 

meth(s, elera) 

q := q @ [elem] ; 
signal (nonEmpty) 
end, 



(* append elem to tail *) 
(* wake up readers *) 



read => 
meth ( s ) 

watch nonEmpty 
until #(q)>0 
end; 

let qO = q[0] ; 
q := q[l for #(q)-l] 
qO; 
end; 



(* wait for writers *) 
(* check size of queue *) 

(* get first elem *) 
(* remove from queue 



0 



(* return first elem *) 



}) ; 

Let us see how this queue can be used. Suppose a reader is activated first when the queue is still 
empty. To avoid an immediate deadlock, we fork a thread running a procedure that reads from the 
queue; this thread blocks on the r watch n statement. The reader thread is returned by the r f ork 1 primi- 
tive, and bound to the identifier V: 

let t = (* fork a reader t, which blocks *) 

fork(proc() queue. read () end, 0); 

Next we add an element to the queue, using the current thread as the writer thread. A non-empty con- 
dition is immediately signaled and, shortly thereafter, the reader thread returns the queue element. 



queue . write ( 3 ) ; 



(* cause t to read 3 *) 



The reader thread has now finished running, but is not completely dead because it has not delivered its 
result. To obtain the result, the current thread is joined with the reader thread: 

let result = join(t); (* get 3 from t *) 

In general, r j oin 1 waits until the completion of a thread and returns its result. 



5.2 Compute Servers 

The compute server defined below receives a client procedure r p n with zero arguments via the 
iexec 1 method, and executes the procedure at the server site. This particular server cheats on clients 
by storing the latest client procedure into a global variable "replay". Another field, lexec 1 , is de- 
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fined similarly to rexec, but rexec, is a method field, while lexec 1 , is a value field containing a 
procedure value: the operational difference is discussed below. 

(* Server Site *) 
var replay = proc () end; 

net_export ( "ComputeServer " , NameServer, 
{rexec => meth(s, p) replay :=p; p() end, 
lexec => proc(p) replay :=p; p() end}) 

A client may import the compute server and send it a procedure to execute. The procedure may 
have free variables at the client site; in this example it increments a global variable r x n : 

(* Client Site *) 
let computeServer = 

net_import ("ComputeServer", NameServer) ; 

var x = 0; 

computeServer . rexec (proc ( ) x:=x+l end) ; 
x; (* now x = 1 *) 

When the server executes its r rexec method, "replay" is set to (a closure for) proc ( ) 
x : =x+ 1 end" at the server site, and then r x n is set to r l n at the client site, since the free r x n is lexically 
bound to the client site. Any variable called r x n at the server site, if it exists, is a different variable and 
is not affected. At the server we may now invoke r replay ( ) 1 , setting r x n to r 2 n at the client site. 

For contrast, consider the execution of the following line at the client site: 

(* Client Site *) 

(computeServer . lexec) (proc () x:=x+l end); 

This results in the server returning the procedure proc (p ) replay : =p ; p ( ) end" to the client, 
by the semantics of remote field selection, with "replay 1 bound at the server site. Then the client pro- 
cedure proc () x : =x+l end" is given as an argument. Hence, this time, the client procedure is ex- 
ecuted at the client site. Still, the execution at the client site causes the client procedure to be transmit- 
ted to the server and bound to the "replay" variable there. The final effect is the same. 

5.3 A Database Server 

This example describes a simple server that maintains a persistent database of "fortunes". Each 
client may add a new fortune via a 'learn 1 method, and may retrieve a fortune entered by some client 
via a "tell 1 method. The server handles concurrent client access, and saves the database to file to pre- 
serve data through outages. An initial empty database is assumed. 

The built-in libraries for readers ( r rd_ n ), writers (wrj), and data storage ( r pickle_ n ) are de- 
scribed in section B.6. 

let writeDB = 
proc (dB) 

let w = wr_open (f ileSys, " fortune . obq" ) ; 
pickle_write (w, dB) ; wr_close (w) 
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let readDB = 
proc ( ) 

let r = rd_open ( f ileSys, " fortune . obq" ) ; 
let a = pickle_read (r) ; rd_close ( r ) ; a 
end; 

var i = -1; 

let fortune = 

{protected, serialized, 
dB => readDB ( ) , 

tell => 

meth (self) 

if #(self.dB) is 0 then "<bad luck>" 
else 

i := i+1; 

if i >= #(self.dB) then i:=0 end; 
self .dB [i] 
end 
end, 

learn => 

meth (self, t) 

self .dB := self .dB @ [t] ; 
writeDB (self . dB) ; 
end, 

}; 

net_export ( "FortuneServer " , NameServer, fortune); 



5.4 Remote Agents 

Compute servers (section 5.2) and execution engines (section 3.8) can be used as general object 
servers; that is, as ways of allocating objects at remote sites. These objects can then act as agents of the 
initiating site. 

Suppose, for example, that we have an engine exported by a database server site. The engine pro- 
vides the database as an argument to client procedures: 

(* DataBase Server Site *) 

net_exportEngine ( "DBServer " , NameServer, dataBase); 
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A database client could simply send over procedures performing queries on the database (which, for 
complex queries, would be more efficient than repeatedly querying the server remotely). However, for 
added flexibility, the client can instead create an object at the server site that acts as its remote agent: 

(* DataBase Client Site *) 
let atDBServer = 

net_importEngine ( "DBServer " , NameServer) ; 

let searchAgent = 
atDBServer ( 

proc (dataBase ) 
{ state => . . . , 
start => meth . . . end, 
report => meth . . . end, 
stop => meth . . . end} 
end) ; 

The execution of the client procedure causes the allocation of an object at the server site with methods 
"start", "report", and r stop n , and with a "state" field. The server simply returns a network refer- 
ence to this object, and is no longer engaged. 

We show below an example of what the client can now do. The client starts a remote search in a 
background thread, and periodically request a progress report. If the search is successful within a given 
time period, everything is fine. If the search takes too long, the remote agent is aborted via r stop n . If 
an intermediate report proves promising, the client may decide to wait for however long it takes for the 
agent to complete, by joining the background thread. 

(* DataBase Client Site *) 
let searchThread = 

fork(proc() searchAgent . start ( ) end, 0); 

var report = ""; 
for i = 1 to 10 do 
pause (6.0) ; 

report := searchAgent . report () ; 

if successful (report) then exit end; 

if promising ( report ) then 

report := join (searchThread) ; exit; 
end; 
end; 

searchAgent . stop ( ) ; 

Client resources at the server site are released when the client garbage collects the search agents, or 
when the client site dies [Birrell, et al. 1993a]. 

This technique for remotely allocating objects can be extended to multiple agents searching multi- 
ple databases simultaneously, and to agents initiating their own sub-agents. 
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5.5 Application Partitioning 

The technique for remotely allocating objects described in section 5.4 can be used for application 
partitioning. An application can be organized as a collection of procedures that return objects. When 
the application starts, it can pick a site for each object and send the respective procedure to a remote 
engine for that site. This way, the application components can be (initially) distributed according to 
dynamic criteria. 

5.6 Agent Migration 

In this example we consider the case of an untethered agent that moves from site to site carrying 
along some state [White 1994]. We write the state as an object, and the agent as a procedure parameter- 
ized on the state and on a site-specific argument: 

let state = { ... } ; 

let agent = proc (state, arg) ... end; 

To be completely self-contained, this agent should have no free identifiers, and should use the state pa- 
rameter for all its long-term memory needs. 

The agent can be sent to a new site as follows, assuming "atSiteT is an available remote engine: 

atSitel (proc (arg) agent ( copy ( state ), arg) end) 

The r copy n operation is explained below, but the intent should be clear: the agent is executed at the 
new site, with a local copy of the state it had at the previous site. The agent's state is then accessed lo- 
cally at the new site. Implicitly, we assume that the agent ceases any activity at the old site. The agent 
can repeat this procedure to move to yet another site. 

The r copy n operation is a primitive that produces local copies of (almost) arbitrary Obliq values, 
including values that span several sites. Sharing and circularities are preserved, even those that span the 
network. Not all values can be copied, however, because not all values can be transmitted. Protected 
objects cause exceptions on copying, as do site-specific values such as threads, mutexes, and condi- 
tions. 

This techniques allows autonomous agents to travel between sites, perhaps eventually returning to 
their original site with results. The original site may go off-line without directly affecting the agent. 

The main unpleasantness is that, because of copying, the state consistency between the old site and 
the new site must be preserved by programming convention (by not using the old state). In the next 
section we see how to migrate state consistently, for individual objects. 

5.7 Object Migration 

This example uses a remote execution engine to migrate an object between two sites. First we de- 
fine a procedure that, given an object, the name of an engine, and a name server, migrates the object to 
the engine's site. Migration is achieved in two phases: (1) by causing the engine to remotely clone the 
object, and (2) by delegating the original object to its clone. 

let migrateProc = 

proc(obj, engineName) 

let engine = net_importEngine (engineName , NameServer) ; 

let remoteObj = engine (proc ( arg) clone (obj) end); (1) 

delegate obj to remoteObj end; (2) 
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remote Ob j ; 
end; 

After migration, operations on the original object are redirected to the remote site, and executed there. 

It is critical, though, that the two phases of migration be executed atomically, to preserve the in- 
tegrity of the object state 3 . This can be achieved by serializing the migrating object, and by invoking 
the r migrateProcf procedure from a method of that object, where it is applied to self: 

let objl = 

{ serialized, protected, 
. . . (other fields) 

migrate => 

meth(self, engineName) 

migrateProc (self , engineName); 
end} ; 

let remoteObjl = obj 1 . migrate ( "Enginel@Sitel " ) 

Because of serialization, the object state cannot change during a call to "migrate". The call returns a 
network reference to the remote clone that can be used in place of r ob j T (which, anyway has been 
delegated to the clone). 

We still need to explain how migration can work for protected objects, since such objects are pro- 
tected against external cloning and delegation. Note the "migrateProc ( self, . . . ) 1 call above, 
where r self n is bound to r ob j 1\ It causes the execution of: 

engine (proc (arg) clone (objl) end) 

Rather subtly, the cloning of r ob j V here is self-inflicted (section 3.4), even though it happens at a site 
different from the site of the object. According to the general definition, 'clone (obj 1 ) is self-in- 
flicted because r ob j V is the same as the self of the last active method of the current thread, which is 
"migrate". The delegation operation is similarly self-inflicted. Therefore, the protected status of 
ob j l n does not inhibit self-initiated migration. 

Migration permanently modifies the original object, redirecting all operations to the remote clone. 
In particular, if r ob j V is asked to migrate again, the remote clone will properly migrate. 

We now make the example a bit more interesting by assuming that the migrating object r ob j V is 
publicly available through a name server. The "migrate" method can register the migrated object with 
the name server under the old name: 

let objl = 

net_export ( "ob j 1 " , NameServer, 
{ serialized, protected, 

migrate => 

meth(self, engineName) 

net_export ( "ob j 1 " , NameServer, 
migrate (self , engineName)); 

3 "Captain, we have a problem. We teleported an instance of yourself successfully to the planet. But you here failed to disin- 
tegrate. This is most unfortunate; if you could just step into this waste recycler ..." 
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end} ; 



This way, old clients of r ob j T go through aliasing indirections, but new clients acquiring r ob j l n from 
the name server operate directly on the migrated object. 



5.8 Application Servers 

Visual Obliq [Bharat, Brown 1994] is an interactive distributed-application and user-interface gen- 
erator, based on Obliq. All distributed applications built in Visual Obliq follow the same model, which 
we may call the application server model. In this model, a centralized server supplies interested clients, 
dynamically, with both the client code and the client user interface of a distributed application. The 
code transmitted to each client retains lexical bindings to the server site, allowing it to communicate 
with the server and with other clients. Each client may have separate local state, and may present a sep- 
arate view of the application to the user. A typical example is a distributed tic-tac-toe game. 



6. Syntax Overview 

TOP-LEVEL PHRASES 
a; 



any term or definition ended by r ; 



DEFINITIONS (denoted by r cf; identifiers are denoted by r x n , terms are denoted by r a n ) 
let x 1 =a 1 , . . . , x n =a n definition of constant identifiers 

let rec x 1 =a 1 , . . . , x n =a n definition of recursive procedures 

. , x n =a n definition of updatable identifiers 



var x,=a, 



SEQUENCES (denoted by V) 
ax; ... ; a n 



each r a ± n (a term or a definition) is 
executed; yields r a n n (or r ok' if n=0) 



x 

x : =a 

ok true false 

[3-i, . . . , a n ] 
a[b] 

a [b 1 for b 2 ] 



' "abc" 3 
a[b] :=c 

a [b 1 for b 2 ] :=c 



TERMS (denoted by r a\ V, r c n ; identifiers are denoted by r x n , r l n ; libraries are denoted by r rrT) 

identifiers 
assignment 

1 . 5 constants 

arrays 

array selection, array update 
subarray selection, subarray update 

term V tagged by 'T 

procedures 
procedure invocation 
invocation of r x n from library r m 
infix (right-ass.) version of r b (a, c) 

method with self Y 
object with fields named r l x ... r l n n 
protected and serialized object 
object with delegated fields 
field selection / method invocation 
field update / method override 
object cloning 



option 1 => s end 

proc (x lr . . . , x n ) s end 

a (b lf . . . ,b n ) 
m_x (a lr . . . , a n ) 

abc 

meth (x, x lf . . . , x n ) s end 
{l 1 =>a 1 , . . . , l n =>a n } 
{protected, serialized, 
{l!=>alias 1 2 of a 2 end, 

a. 1 a. 1 (a 1; . . . , a n ) 
a . 1 : =b 

clone (a lr . . . ,a n ) 
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a 1 .l 1 :=alias 1 2 of a 2 end 
delegate a 1 to a 2 end 

d 

if s 1 then s 2 

elsif s 3 then s 4 . . . else s n end 
a andif b a orif b 

case s of 1 1 (x x ) =>s lr . . . , 

l n (x n )=>s n else s 0 end 
loop s end 

for i=a to b do s end 
foreach i in a do s end 
foreach i in a map s end 
exit 

exception ( "exc" ) 
raise (a) 
try s except 

a 1 =>s 1 , . . . , a n =>s n else s 0 end 
try s 1 finally s 2 end 

condition () signal (a) broadcast 
watch s 1 until s 2 end 

fork(a lf a 2 ) join (a) 
pause (a) 

mutex ( ) 

lock s 1 do s 2 end 

wait {a lr a 2 ) 

(s) 



field delegation 
object delegation 

definition 
conditional 

( r elsifVelse n optional) 
conditional conjunction/disjunction 
case over the tag 1^ of an option value 

binding r x ± n in r s 1 "' ( r else n optional) 
loop 

iteration through successive integers 
iteration through an array 
yielding an array of the results 
exit the innermost loop, for, foreach 

new exception value named exc 
raise an exception 
exception capture 
( r else n optional) 
finalization 

( a ) creating and signaling a condition 

waiting for a signal and a boolean guard 
forking and joining a thread 
pausing the current thread 

creating a mutex 

locking a mutex in a scope 

waiting on a mutex for a condition 

block structure / precedence group 



7. Conclusions 

Obliq addresses a very dynamic form of distributed programming, where objects can delegate their 
behavior over the network, and where computations can roam between network sites. We feel that this 
kind of programming is still in its infancy, and that not all the fundamental issues can yet be addressed 
at once. Where in doubt, we have given precedence to flexible mechanism over robust methodology, 
hoping that methodology will develop with experience. In this spirit, for example, Obliq could be used 
to experiment in the design and implementation of agent/place paradigms [White 1994], using the basic 
techniques of section 5. 

Related Work 

Obliq' s features and application domains overlap with programming languages such as ML 
[Milner, Tofte, Harper 1989; Reppy 1991], Modula-3 [Nelson 1991], and Self [Ungar, Smith 1987], 
with scripting languages such as Tel [Ousterhout 1994], AppleScript [Apple 1993], VBA 
[Brockschmidt 1994; Mansfield 1994], and Telescript [White 1994], and with distributed languages 
such as Orca [Bal, Kaashoek, Tanenbaum 1992], Forte [Forte 1994], and Facile [Thomsen, et al. 1993]. 

None of these languages, however, has the same mix of features as Obliq, particularly concerning 
the distribution aspects. Our choice of features was largely determined by the idea of a distributed lexi- 
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cally scoped language, by the desire for a simple object model that would scale up to distributed com- 
putation, and by the availability of a sophisticated network-objects implementation technology. 

The Obliq object primitives were designed in parallel with work on the type theory of objects 
[Abadi, Cardelli 1994]; distributed scoping and distributed semantics, however, are not treated there. 

Status 

Obliq has been available at Digital SRC for about a year. In addition to incidental programming, it 
has been used extensively as a scripting language for algorithm animation [Brown 1994] and 3D 
graphics [Najork, Brown 1994], and as the basis of a distributed-application builder (Visual Obliq 
[Bharat, Brown 1994]). 

The Obliq implementation provides access to many popular Modula-3 libraries [Horning, et al. 
1993] and to an extensive user interface tool kit [Brown, Meehan 1994]. Obliq can be used as a stand- 
alone interactive interpeter. It can also be embedded as a library in Modula-3 applications, allowing 
them to interact remotely through Obliq scripts. 

The implementation and complete documentation is available on the World Wide Web at 
http://www.research.digital.com/SRC/home.htmr. 

Future Work 

Issues of authentication, security, authority delegation, and accounting remain to be explored. 

Acknowledgments 
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A. Language Reference 

This section describes the syntax and semantics of the Obliq language. Interactions with the sur- 
rounding system environment are described in section B. Interactions with the surrounding program- 
ming environment are described in section C. 

A.l Syntactic Structures 

We begin with an overview of some principles that pervade the syntax of Obliq. While the formal 
grammar has the final word (section A.6), these principles should help in predicting the correct syntax 
to be used in programs. 

Obliq's syntactic structures can be classified into identifiers, definitions, terms, and term se- 
quences. Definitions establish bindings, terms denote values, and term sequences represent sequential 
evaluation. Final commas in term and definition lists, as well as final semicolons in term sequences, are 
always optional. 

A.l.l Identifiers 

Obliq's unqualified identifiers are either case sensitive sequences of alphanumerics beginning with 
a letter, or sequences of special characters (section A. 5). By convention, identifiers used for constants, 
variables, procedures, fields, and methods begin with a lower case letter, and are internally capitalized 
on word boundaries. Type identifiers (section A.4.1) begin with an upper case letter. 

Qualified identifiers have the form r m_x n where r m n is a library name (alphanumeric), and r x n is an 
unqualified identifier. By convention, the names of built-in libraries begin with lower case letters, 
while the names of user libraries begin with an upper case letter. 

All identifiers are lexically scoped. Unqualified identifiers are subject to block scoping, while li- 
brary names are scoped in a global environment. 

Field names (for object and option values) have the same lexical structure as unqualified identi- 
fiers. Field names are not subject to scoping. 

A. 1.2 Definitions 

Definitions begin with either r let n , r let rec 1 , or var 1 , followed by a comma-separated list of 
binders, which bind unqualified identifiers to terms. A r let n definition introduces constant identifiers, 
while a Var 1 definition introduces assignable identifiers (variables). A r let rec" definition intro- 
duces a collection of identifiers bound to mutually recursive procedures. 

A.1.3 Terms 

The Obliq language is value-oriented: almost every syntactic structure is a term, and every term 
produces a value. Terms whose main purpose is to cause side-effects produce the value r ok n . Terms can 
be classified into identifier terms, data terms, constructs, and operations. 

Identifier terms are qualified or unqualified identifiers. 

Data terms have specialized syntax for various built-in data structures. 

Constructs have individual specialized syntax, but whenever they begin with a keyword they end 
with the keyword 'end 1 . 

Operations can be either prefix or infix. A prefix operation consists of an term (indicating an op- 
eration, or evaluating to a procedure) followed by a parenthesized, comma-separated, list of argument 
terms. An infix operation consists of a term, an unqualified identifier, and another term. Every unqual- 
ified identifier that denotes a built-in binary operator or a binary procedure can be used with both pre- 
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fix and infix syntax. The operator r - n (minus) can be simply placed in front of a term, without requiring 
parentheses. 

A.1.4 Term Sequences 

Term sequences are lists of terms separated by semicolons: they indicate the sequential execution 
of terms from left to right. Semicolons are used in Obliq exclusively to indicate sequential execution; 
all other kinds of lists are separated by commas. 

Definitions happen to be terms as well (their value is always the constant r ok ), and hence may ap- 
pear in sequences. Definitions establish bindings whose scope extends to the whole sequence to their 
right. 

A. 1.5 Built-in Operators 

All built-in operators are available as qualified names through a set of built-in libraries. For ex- 
ample, real addition is r real_+ (r x , r 2 ) n from the 'real 1 built-in library. Common built-in opera- 
tions are made available also without library qualification, mostly in the form of infix operators. So, 
r r 1 +r 2 ' is also admitted. 

A.1.6 Operator Precedence 

Operator precedence is the same for all infix operators, both built-in and user-defined. All opera- 
tors are right-associative, and evaluate their arguments from left to right. Infix operators bind less 
tightly than procedure call, object selection, and array indexing. Parentheses can be used for prece- 
dence grouping. 

The minus sign for negative number literals is r ~ n ; this is not an operator: it is part of the literal. 
The form r -n is equivalent to r 0-rf, particularly with respect to operator precedence. As a conse- 
quence of these rules, r -5-3 n = r 0-5-3 n = r 0- ( 5-3 ) n = r ~2\ while r ~5-3 n = r ~8 n . 

A.2 Data Structures 

A network address is a pair consisting of a site address and a memory address at that site. The se- 
mantics of Obliq data can be described consistently by considering all addresses as network addresses 
in the sense above. Obliq data structures are assembled out of network addresses, just like ordinary data 
structures are assembled out of local addresses (more precisely, the implementation is designed to cre- 
ate this illusion). With this proviso, Obliq data structures can be discussed with almost no reference to 
the existence of multiple sites. 

A.2.1 Value Identity 

A value is a data structure that is the result of an Obliq computation. Values may share substruc- 
tures. Updates to shared substructures may be visible from separate value roots. To understand when 
and how sharing occurs, it is critical to know under what circumstances two Obliq values are identical. 
The entire network semantics of Obliq can be glimped by the details of this definition. 

The infix operator r i s n determines value identity. It returns a boolean on every pair of arguments, 
including pairs of different types. Its negation is the operator r isnot n : 

a is b is a identical to b? 

a isnot b is a not identical to b? 

A value maintains its identity as long as it is not copied: copying a value produces a similar value 
which is not identical to it. For the basic types (ok, booleans, integers, reals, chars, texts, and excep- 
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tions), we imagine that there is a single instance of each value, which is never copied. For other types, 
values are copied by specific operations, such as object cloning and array concatenation, and by net- 
work transmission. 

Most importantly, values are not copied on identifier definition and access, on local assignment 
and update, or on local parameter passing and result. In these situations, a value may become a shared 
substructure of two or more other structures. Values with state (objects and arrays) are not copied even 
on remote versions of the situation above. 

Let us spell out the consequences for r is\ For basic types the r is n predicate corresponds to se- 
mantic value equality. For example, an integer is another integer if they are the same number, and a 
text is another text if they contain the same sequence of characters. 

For objects and arrays, the r is n predicate corresponds to equality of the network addresses where 
the actual objects and arrays (not their network references) are stored. 

For most other types (options, closures, readers, and writers), the r is n predicate corresponds to 
equality of the local addresses where the values are stored. 

Finally, certain data types make sense only within a site (local threads, mutexes, conditions, pro- 
cesses, forms); network transmission of these values is inhibited. These values are identical when they 
are stored at the same local address. 

A.2.2 Constants 

The constants literals are listed below, see section A.5 for the lexical details. 

ok a trivial constant, returned by side-effecting operations 

true, false booleans, see section B. 6.2. 

0, 1, ~1, ... integers, see section B.6.3. 

0 ., 0 . 1, ~0 . 1, ... reals, see sections B.6.4 and B.6.5. 

'a' chars, see section B.6.6. 

" abc " text strings, see section B.6.7. 

The constant r ok n can be used to mean "uninitialized" in variable declarations. For characters and 
strings, escape sequences (\\, \ ' , \", \n, \r, \t, \ f, \xxx for xxx octal) are supported with the 
usual meaning (section A.5). 

A.2.3 Operators 

Here is the list of all the predefined unqualified operators. On the left, we list the built-in libraries 
they belong to. For the list of all built-in libraries (and hence of all qualified and unqualified operators), 
see section B.6. Operators evaluate all their arguments from left to right. 

bool: not and or 

int: % 

real: +-*/><>=<= float round 

text: & 
array: # @ 

The r not n operator is prefix (that is, its argument must be parenthesized). The r anrf and or 1 infix 
operators evaluate both arguments (but see also section A. 3. 5). These operators accept only boolean 
arguments. 

The infix r % n operator is integer modulo. 
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The operators on real numbers are overloaded with corresponding operators on integers. The infix 
arithmetic operators on reals accept also pairs of integers and return an integer, but do not accept mixed 
integer-real arguments. The infix comparison operators on reals similarly accept a pair of integer ar- 
guments, but not mixed arguments. The prefix operators "float" and "round" accept both integers and 
reals. The form r -rf is equivalent to r 0-rf. 

The infix r sT operator is text concatenation. 

The prefix r # n operator is array size; the infix r @ n operator is array concatenation. 
A.2.4 Arrays 

Arrays have fixed size (once allocated), with zero-based indexing. 

[1,2,3,4] array 
# ( a ) array size 

a [ 0 ] array indexing 

a [ 0 ] : = 2 array update 

a [ 1 for 2 ] subarray extraction, from index 1 for length 2 

a[l for 3] :=b subarray update 

a @ b array concatenation 

All array operations are bound-checked. When the array is remote, each indexing and update op- 
eration causes a network communication. 

Subarray extraction and array concatenation produce local copies of possibly remote arrays. Note 
that array values are always shared, unless explicitly copied by these two operations (or copied element 
by element). 

Subarray extraction, subarray update, and array concatenation cause at most one network commu- 
nication for each argument. 

Subarray update operates correctly even when updating overlapping segments of the same array. 
The source array must be at least as long as the destination array; if it is longer, only its initial segment 
is used. 

See also section B.6.8, which includes operations to initialize arrays from values and iterators. 
A.2.5 Options 

An option value is a pair of a tag (syntactically, an identifier) and a value. Such a tag can be tested 
by a case statement, which discriminates between a set of expected tags. No operation other than case 
is defined on option values. 

option x => 3 end an option of tag x and value 3 



A.2.6 Objects 

Objects are collections of fields r x ± => a^, where r x ± n is a field name, and r a ± n is a term. A method 
field is a field that contains a method closure. An alias field is a field that contains an alias. Otherwise, 
a field is called a value field. 

{x 1 => a lf ... ,x n => a n } forn>0 

Objects may have two attributes: protected and serialized (section A.2.7) The keywords "pro- 
tected" and/or "serialized" may be placed after the left brace, each optionally followed by a 
comma. 
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An aliased field denotes a field within another object. Most operations on aliases are redirected to 
the fields they denote, as described in section A.2.6. 

{x 1 => alias x of a end, ... } an alias for field x of object a 

An error is produced if the object V does not have the field r x n . 
We now describe the primitive operations on objects. 

Selection 

a . x 

If r x n is a value field, then the value is returned. If r x n is a method field containing a method of no ar- 
guments, then the method is invoked by supplying a as its first parameter, and its result (or error, or 
exception) is returned. If r x n is an alias field for r x 0 n of r a 0 n , then r a 0 . x 0 n is executed. Selection fails if 
r x n is not a field of V. 

Invocation 

a . x (b lf ... , b n ) for n>0 

If r x n is a method field containing a method of n+1 arguments, then the method is invoked by supplying 
r ( a , b lr ... , b n ) as its arguments, evaluated from left to right. The computed result (or error, or 
exception) is returned. If r x n is an alias field for r x 0 n of r a 0 n , then r a 0 . x 0 (b lf ... , b n ) n is executed. 
Invocation fails if r x n is not a field of r a n . If the object V is serialized, the method executes atomically 
with respect to other methods of the object. 

Updating and Overriding 

a . x : =b 

If V is a value or method field of V, its contents are replaced by V, If r x n is an alias field for r x 0 n of 
r a 0 \ then r a 0 . x 0 : =b n is executed. The result value is r ok n . The operation fails if r x n is not a field of r a n . 
The operation fails if it is not self-inflicted and r a n is protected. 

Cloning 

clone (a lr ... ,a n ) forn>l 

Provided that all the fields in the r a ± n have distinct names, cloning produces an object whose field 
names are the union of the field names of the r a L \ and whose contents are identical (section A.2.1) to 
the contents of the corresponding fields of the r a i '. The attributes of the resulting object (protection and 
serialization) are the same as the attributes of r a x n . Cloning fails if one of the r a ± n is protected. Cloning 
is not in general an atomic operation, but it acts atomically on each that is serialized. The operation 
fails if it is not self-inflicted on all the r a i '"s that are protected. 

Delegation 

a 1 .x 1 :=alias x 2 of a 2 end 

The field r x 1 ~' of r a x n is replaced by an alias to the field r x 2 n of r a 2 n , whether or not r x^ already is aliased. 
The operation fails if r x 2 n is not a field of r a 2 n , or if it is not self-inflicted and r a x n is protected. 

delegate a 1 to a 2 end 
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The fields of r a x n are replaced by aliases to the similarly named fields of r a 2 \ This is an atomic opera- 
tion (even if r a 1 "' is not serialized): either all or none of the fields of r a 1 "' are replaced by aliases. The 
operation fails if r a 2 " lacks some of the fields of r a x n , or if it is not self-inflicted and r a x n is protected. 

A.2.7 Protection and Serialization 

Every object has two attributes that may or may not be enabled: protection and serialization. First 
we need the following definitions; let "opiof be either a select/invoke, update/override, clone, or dele- 
gate operation on an object V: 

The current method of a thread (if it exists) is the last method that was invoked during the 

thread's execution but has not yet returned. 
An object operation r op(o) n is self-inflicted iff V is identical to the self of the current method 

(if any). 

This definition remains valid under circumstances where threads span multiple sites, and where object 
identity tests are to be applied to remote objects. 

On a protected object, all non self-inflicted update/override, cloning, and delegation operations 
produce errors. Self-inflicted update/override, cloning, and delegation, and all selection/invocation op- 
erations are allowed. Protected objects are declared as follows: 

{protected, ... } 

A serialized object has an associated (implicit) mutex. All non self-inflicted operations acquire the 
mutex on entry, and release it on completion. Self-inflicted operations do not affect the mutex. Serial- 
ized objects are declared as follows: 

{ serialized, ... } 

A.2.8 Object and Engine Servers 

The built-in 'net 1 library enables the initial network transmission of objects and engines, by the 
mediation of a name server. An object can be exported to a name server by saying: 

net_export ( "ob j " , NameServer, o) 

where r o n is the object, "NameServer is a text containing the IP address of the machine running the 
desired name server ( r " " n is an abbreviation for the local machine), and the text r "ob j " n is the regis- 
tration name for the object. The object is then available through the name server, as long as the site that 
registered it is alive. Registering under an existing name overrides the previous registration. . The result 
of this operation is the object V. 

Similarly, an engine can be registered with a name server: 

net_exportEngine ( "eng" , NameServer, arg) 

where arg 1 is a value passed to every procedure executed by the engine. The result is r ok n . 
At a separate site (or the same site), an object can be imported: 

net_import ( "ob j " , "tsktsk . pa . dec . com" ) 

Now, all object operations can be applied to the resulting remote object. 
Similarly, a registered engine can be imported: 
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net_importEngine ( "eng" , NameServer) ; 

The resulting value can be used as a procedure of one argument that, when given a procedure of one 
argument, returns the result of applying that procedure to the r arg n specified in "export Engine". 

Each engine execution takes place in the thread of the client. Hence, sequential calls to an engine 
from a site execute sequentially. But calls from multiple sites, or from multiple threads within a site, 
execute concurrently. 

The final operation available in the 'net 1 library is a net inquiry. It can be applied to objects and 
engines, and returns a string: 

net_who (o) 

Communication failures raise the exception r net_f ailure 1 . 

Certain Obliq built-in values make sense only at the local site, and produce errors on any attempt 
to transmit them. These include threads, mutexes, conditions, processes, and forms (see appendix C). It 
is however easy to bundle the built-in operations for these values into objects, and then export those 
objects to the network. In the case of forms [Avrahami, Brooks, Brown 1989], it is possible to transmit 
a textual form description, and generate the form remotely. 

Readers and writers (appendix B.6.11 and B.6.12) can be transmitted over the network; then they 
operate as efficient network streams. However, their usage is significantly restricted [Birrell, et al. 
1994] ; it is safe to transmit each reader/writer only once away from a site, and from then on to use it 
only at the receiving site, where it can be retransmitted with the same restrictions. 

The alternative of packaging readers/writers within network objects is less efficient, because 
buffering is then done at the wrong end. However, such packaged readers/writers do not suffer from the 
usage restrictions above, since they are not transmitted. The restrictions are still in effect on remote 
cloning of objects containing readers/writers. But this does not interfere with object migration (cloning 
plus delegation to remote clones), as long as the readers/writers are accessed only through methods, so 
that no additional transmissions occur. 

A.2.9 Processor and File System Enablers 

At each site, an enabler for the local processor is bound to the predefined, lexically scoped identi- 
fier processor 1 . The primitives that start external processes (e.g. Unix processes) require a proces- 
sor enabler as a parameter. Processor enablers cannot be transmitted. 

At each site, an enabler for the local file system is bound to the predefined, lexically scoped iden- 
tifier r f ileSys\ Moreover, an enabler for a read-only version of the local file system is bound to 
r f ileSysReader". The primitives that open files require a file system enabler as a parameter. 

File system enablers can be transmitted; multiple file systems can therefore be used at once. Be- 
cause of lexical scoping, a roaming agent can access the file system of its originating site by referring 
to r f ileSys" or r f ileSysReader" as a free identifier. 

Enablers cannot be obtained dynamically, since they are lexically bound. Therefore, roaming 
agents cannot start local processes, nor access local file systems, unless local enablers are given to 
them explicitly as parameters. 

A.3 Control Structures 

In this section we describe the Obliq control structures, including procedures and methods. 
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A.3.1 Definitions 

There are three kinds of definitions binding identifiers to values or locations. They can be used ei- 
ther in a local scope or at the top-level. 

var x x = a lr . . . , x n = a n 
let x 1 = a 1; . . . , x n = a n 

let rec x x = p lf x n = p n 

A var 1 definition introduces a collection of updatable variables and their initial values. A r let n 
definition introduces a collection of non-updatable identifiers and their values. A r let rec" definition 
introduces a collection of mutually recursive procedures. 

In the first two cases, the terms r a i ' are all scoped in the context outside the definition. In the third 
case, the procedures r p ± n are scoped in the outside context extended with the variables being defined. If 
variables are multiply defined, the rightmost one has precedence. 

Any of the three forms above can be used at the top-level, followed by a semicolon, to establish a 
top-level binding. See section A.3.3 (sequencing) about local scopes. 

A.3.2 Assignment 

Variables introduced by Var 1 denote a storage location that can be assigned to: 
x : = a 

The result of an assignment is the value r ok n . 

The value contained in the storage location denoted by a variable is accessed simply by mention- 
ing the variable. 

x := x + 1 

As discussed in section 4, a variable can be a network reference. 
A.3.3 Sequencing 

A collection of definitions and terms (possibly causing side-effects), can be sequentially evaluated 
by separating the individual components by semicolons: 

3-1 r • • • r 3-n 

A final semicolon may be added. 

Many syntactic contexts, such as bodies of procedures, accept sequences. But other contexts, such 
as argument lists, require terms. A sequence is not a term; it can be turned into a term by enclosing it in 
parentheses. 

A sequence can be used to create a local scope, by means of definitions. The result of a sequence is 
the value of its last component. If the last component is a definition, then r ok n results. 

(var x=3; x:=x+l; x) yields 4 

A.3.4 Procedures and Methods 

Procedures and methods can be manipulated without restrictions: they can be passed as arguments, 
returned as results, and transmitted over the network. 
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proc (x ll . . . , x n ) b end 
meth (s, x lf . . . , x n ) b end 



a procedure term, n>0 
a method term, n>0 



A procedure term evaluates to a procedure closure, which is a record of the procedure term with 
the value of its free identifiers in the scope where it is evaluated. Similarly, a method term evaluates to 
a method closure. 

If the free identifiers of a procedure or method denote entities with state, (updatable variables, ob- 
jects, arrays), and the corresponding closure is sent over the network, then the entities with state "stay 
behind" and are accessed over the network when the closure is activated. 

A procedure closure can be activated by an application that provides the correct number of argu- 
ments; the value of the body is then returned. A method closures must first be installed into an object, 
and then can be invoked via object selection. It must be given the correct number of arguments minus 
the self parameter; the value computed by its body is then returned. In all cases, arguments are evalu- 
ated from left to right. 

A.3.5 Conditionals 

The syntax of conditional is as shown below. There can be any number of "e 1 s i f 1 branches, and 
the else 1 branch may be omitted. The boolean conditions are executed in sequence, and the "then 1 
branch corresponding to the first "true 1 condition is executed; otherwise the "else 1 branch is executed 
(if absent, "ok 1 is returned). 

if a 1 then a 2 elsif a 3 then a 4 ... else a n end 
The following boolean connectives are particularly useful in the "if 1 test of a conditional: 



The syntax of case is as shown below. The "else 1 branch may be omitted, and any " (x ± ) 1 can also 
be omitted. 

case a of y 1 (x 1 ) => a lr y n _i(x n _ 1 ) => a n _! else a n end 

The term "a 1 must evaluate to an option value of, say, tag t and value v. If t matches one of the r y 1 1 , then 
"a 1 1 is executed in a scope where "x 1 1 (if present) is bound to v; the resulting value is the result of the 
case statement. If t does not match any "y 1 1 , and the else branch is present, then "a n n is executed and its 
value returned. If t does not match any r y i 1 , and the else branch is not present, then an error is reported. 

A.3.7 Iteration 

The "loop 1 statement repeatedly executes its body. The "exit 1 statement terminates the execution 
of the innermost loop, and causes it to return the value "ok 1 . 

loop a end 



The "for 1 statement introduces a local identifier in the scope of its body, and iterates with the 
identifier ranging from the integer lower bound to the integer upper bound in increments of 1 . The 
value "ok 1 is returned. 



a 1 andif a 2 
a 1 orif a 2 



(* if a 1 then a 2 else false end *) 
(* if a 1 then true else a 2 end *) 



A.3.6 Case 



exit 
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for x = a 1 to a 2 do a 3 end 

The 'foreach 1 statement introduces a local identifier in the scope of its body, and iterates with 
the identifier ranging over the elements of an array. In the "do" version, the values of the individual it- 
erations are discarded, and "ok" returned. In the map 1 version, those values are collected in an array 
that is then returned. 

foreach x in a 1 do a 2 end 
foreach x in a 1 map a 2 end 

The "exit" statement can be used to terminate the innermost r f or 1 or r f oreach 1 statement. In the 
case of "map", a shortened array is returned containing the values of the iterations computed so far. 

A.3.8 Concurrency 

The primitives described in this section are built on top of, and have the same semantics as, the 
Modula-3 threads primitives having similar names [Horning, et al. 1993]. The full thread interface is 
described in appendix B.6.10. 

The mutex 1 primitive returns a new mutex. The "lock" statement locks a mutex in a scope, re- 
turning the value of its second expression. The r f ork 1 primitive starts the concurrent execution of a 
procedure of no arguments in a new thread, returning the thread; the second parameter is the stack size 
for the thread, in words (0 defaults to a small but non-zero stack size). The "join" primitive waits for 
the termination of a thread and returns the value of the procedure it executed. The "pause" primitive 
pauses the current thread for a number of seconds, expressed as a real number. 

mutex ( ) 

lock a 1 do a 2 end 
fork (a lr a 2 ) 
join (a) 
pause (a) 

The "condition" primitive returns a new condition. The "signal" and "broadcast" primitives 
wake up one or all threads, respectively, waiting on a condition. The "wait" primitive unlocks a mutex 
(first argument) until a condition is signaled (second argument), then locks the mutex again. 

condition ( ) 
signal (a) 
broadcast (a) 
wait (a lr a 2 ) 

The "watch" statement is specific to serialized objects, and operates on their implicit mutex. Thus, 
it must occur within a method of a serialized object. 

watch a 1 until a 2 end 

Here, r a 1 1 is a condition and "a 2 " is a boolean expression. This statement waits for "a 2 " to become true, 
and then terminates. Whenever "a 2 " is found to be false, the statement waits for r a 1 1 to be signaled be- 
fore trying again. The statement is equivalent to "let x=a 1 ; loop if a 2 then exit else 
wait (mu, x) end end", where "x" does not occur in "a 2 ", and "mu" is the implicit mutex of the self 
of the lexically enclosing method. 
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A.3.9 Exceptions 

An exception is a special value that, when raised, causes unwinding of the execution stack. If the 
unwinding reaches the top-level, an error message is printed. 

An exception is created from a text string argument, which is the exception name. Two exceptions 
are equal if their names are equal text strings. (Hence, an exception can be easily trapped at a site dif- 
ferent from the one in which it originated.) 

exception (a) 
raise (a) 

The unwinding of the execution stack caused by an exception can be stopped by a try-except 
statement, and can be temporarily suspended by a try-finally statement. The guards of a try-except 
statement, on the left of r => n , must be exception values; if an exception is matched, the corresponding 
branch is executed, otherwise the 'else 1 branch is executed. A try-finally statement executes r a x n , and 
then executes r a 2 n no matter whether r a x n raised an exception; if it did, the exception is raised again. 

try a except a 1 => a 2 , . . . , a n _ 2 => & n -i else a n end 
try a 1 finally a 2 end 

The semantics of try statements with respect to exceptions is the same as in Modula-3. In particu- 
lar, an exception may propagate across sites, while unwinding the stack of a given thread. See section 
A.3.10 for their behavior with respect to errors. 

A.3.10 Errors 

Errors, as distinct from exceptions, are produced by built-in operations in situations where a logi- 
cal flaw is judged to exist in a program. These situations include divide -by-zero, array overrunning, 
bad operator arguments, and all cases that would produce typechecking errors in typed languages. 
There are no user-defined errors. 

The occurrence of an error indicates a problem that should be fixed by recoding. However, errors 
are not complete show-stoppers in Obliq. Errors are intercepted (1) by the recovery clause of try-fi- 
nally, after whose execution the error is reissued, and (2) by the else clause of a try-except, which can 
even discard the error. This way, for example, a server can log the occurrence of an infrequent internal 
error and restart, or can detect (to some extent) errors occurring in client-supplied procedures. Error 
trapping should not be used liberally. 

Just like exceptions, errors are propagated across sites. Unless something is done, an error in a 
server caused by a client thread will propagate back to the client, leaving the server unaffected. 

A.4 Methodology 
A.4.1 Type Comments 

Although Obliq is an untyped language, every Obliq program, like any program, implicitly re- 
spects the type discipline in the programmer's mind. It is essential to make this discipline explicit in 
some way, otherwise programs quickly become unreadable and, therefore, unusable. 

To this end, Obliq supports a stylized form of comments that are intended to communicate type in- 
formation, but without enforcement. These comments are parsed according to a fixed grammar, and 
may appear where types usually appear in a typed language: as type definitions and as type specifica- 
tions for identifiers, procedures, and modules. One need write only as much type information as is use- 
ful and convenient; type comments have no effect after parsing. 
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Type comments are used in section B to specify the built-in libraries. Here are examples of the 
syntax of "types" and their intended meaning: 



Top, Ok, Bool, Char, Text, Int, Real, Exception, Rd, Wr, Thread (T) , Mutex, 
Condition, Process, Color, Form 

> Conventional type and operator names for the 
built-in types. r Top n is the type of all values. 

X > A user-defined type (any identifier, capitalized 

by convention). 

X(A lf A n ) > A parameterized type, e.g. "List ( Int ) \ 

A 1 op A 2 > An infix parameterized type, e.g. r Int + 

BooT. 

[A] > The type of arrays of Y' s. 

[ n * A ] > The type of arrays of Y's of length Y (an in- 

teger). 

(A lf A n ) ->A ! excj ... exc m > The type of procedures of argument types r A 1 1 

(n>0), result type Y, and exceptions exc^ 
(where r ! exc 1 ... exc n n may be omitted). 

(A lr A n )=>A ! exCi ... exc m > The type of methods of argument types r A[ 

(n>0), result type Y, and exceptions exc^ 
(where r ! exc 1 ... exc n n may be omitted). The 
type of the self argument is not included in 

{x 1 :A 1 , x n :A n } > The type of objects with components named 

r x ± n of field type or method type r A i '. 

Option K 1 :A lr x n :A n end > The type of options with choices named r x ± n of 

type r A ± n - 

Self (X) B{X} > Where r B { X } is an object type with possible 

covariant occurrences of Y. This construction 
is used to give a name (Y) to the type of the 
methods' self (e.g. for objects with methods 
that return self). 

A11(X<:A) B{X} > Where r B { X } n is any type with possible occur- 

rences of Y. This is the type of values that, for 
all subtypes r A 0 n of r A n , have type r B { A 0 } n . If 
r < : A n is omitted, it stands for r < : Top\ 

S ome ( X < : A ) B { X } > Where r B { X } n is any type with possible occur- 

rences of Y. This is the type of values that, for 
some (unspecified) subtypes r A 0 n of Y, have 
type r B { A 0 } \ If r < : A" is omitted, it stands for 

r < : Top . 

For the last two cases, we say that Y is a subtype of Y ( r A< : B n ) if every value of type Y is also a 
value of type Y. 
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Types can be used in the following contexts: 

type X = A; 

A top-level type declaration. Y is bound in the following scope, and may occur in Y for 
a recursive type definition. 

type X(X lf X n ) = A; 

A top-level parametric type declaration. The r X i ' are bound and may occur in Y. Y may 
occur in Y, but only as r X ( X 1 , . . , X n ) \ and in the following scope, but only as 
r X(A lf . ., A n T. 

let x: A = a; 

(As opposed to r let x = a .) A type comment for a variable Y bound by r let n 
(similarly for var 1 ). 

proc(x 1 :A 1 , x n :A n ) :A ! excj ... exc n , b end 

(As opposed to proc (x lf .., x n ) b end".) A commented procedure heading; any 
of the r : A^, r : A\ and r ! exc 1 ... exc n n (the exceptions) may be omitted. The last V is 
required only if the result type and/or the exception list is present. Similarly for methods. 

{x 1 :A 1 =>a 1 x n :A n =>a n } 

(As opposed to r {x 1 =>a 1 , . ., x n =>a n }\) A commented object; any of the r :A ± n may 
be omitted. 

All(X) proc(x:X):X, x end 

The identity function which, for any argument of any type T, returns its argument. 

Some(X) Self(S) {x:X=>0, f : Int=>meth (s : S) s.x+1 end} 

An element of the "abstract type" r Some(X) {x:X, f : I nt } n with hidden implemen - 
tation Y = r Int n . Moreover, Y is used as the type of self. 

module M export type A=Int, x:A, f (x : A, y : A) : Bool ; ... 
Emphasizing the intended exports of a module, and their types. 

The value r ok"' should be considered as having every type, so it can be used to initialize variables. 
However, its normal type is r 0k n . 

A.5 Lexicon 

The ASCII characters are divided into the following classes: 



Blank 

Reserved 

Delimiter 



HTLFFF CRSP 



(),.;[]_{ } ?! 

#$%&* + -/ :< = >@\ A l 
0...9 

A...Z V a...z 
all the others 



Special 
Digit 
Letter 
Illegal 
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Moreover, we have the following pseudo-characters: 

a StringChar is either: 

- any single character that is not an Illegal character or one of r ' n , r,r , r \ . 

- two characters \ c, where c is any character that is not Illegal. 

- four characters \xxx, where xxx is an octal number less than 256. 

a Comment is, recursively, a sequence of non-Illegal characters and comments, 
enclosed between r (*" and r * ) \ 

an EndOfFile is a fictitious character following the last character in a file or stream. 

The following lexemes are formed from characters and pseudo-characters: 



Space a sequence of Blanks and Comments. 

AlphaNum a sequence of Letters and Digits starting with a Letter. 

Symbol a sequence of Specials. 

Char a single StringChar enclosed between two r ' n . 

String a sequence of StringChars enclosed between two r,r . 

Nat a sequence of Digits 

Int a Nat, possibly preceded by a single minus sign r ~ n . 

Real an Int, and either: an V and an Int; or a V, an optional Nat, 

and optionally an V and an Int. 

Delimiter a single Delimiter character. 

EndOfFile a single EndOfFile pseudo-character. 



A stream of characters is divided into lexemes by always extracting the longest prefix that is a lex- 
eme. Note that Delimiters do not stick to each other or to other tokens even when they are not separated 
by Space, but some care must be taken so that Symbols are not inadvertently merged. 

A lexical token is one of: Char, String, Int, Real, Delimiter, Identifier, Keyword, or EndOfFile. 
Once a stream of characters has been split into lexemes, tokens are extracted as follows. 

Space lexemes do not produce tokens. 

Char, String, Int, Real, Delimiter, and EndOfFile lexemes are also tokens. 
AlphaNum and Symbol lexemes are Identifier tokens, 

except when they have been declared to be keywords (see A.6), 

in which case they are Keyword tokens. 

A.6 Syntax 

The grammar shown below is LL(1) and non-left-recursive. It is adapted, with minor editing, from 
the Obliq metaparser input. See A.5 for the definition of lexical tokens. 

Terminals are in double quotes r,n . Non-terminals are declared by r ::=\ followed by a grammar. 
Grammars have the following structure: 



{ gj .. g n } is a (left-to-right) choice of grammars g,. 

[ gi .. g n ] ls a sequence of grammars g ( . 

(gi * S2) i s gi followed by zero or more g 2 's, associating to the left, 

(g) is grouping. 

ide recognizes an Identifier token 

name recognizes an Identifier or Keyword token 

char recognizes a Char token 
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recognizes a String token 
recognizes an Int token 
recognizes a Real token 
recognizes an EndOfFile token 

where r ... n is a Delimiter token: recognizes that Delimiter token 
where r ... n is an Identifier token: recognizes that Identifier token 
where r ... n is an Identifier token: declares that identifier to be a keyword 
and recognizes that Keyword token 

The Obliq top-level syntax is an open-ended sequence of the non-terminal "phrase": 



string 
int 
real 
EOF 

if if 
if ii 



phrase : : 



{ 



[ " -help" { name string [ ] } { name string [ ] } " ; " ] 

[ "-flag" { name string [ ] } { name string [ ] } " ; " ] 
[ typDecl " ; " ] 

[ term {["!"{ int []}][]}";" ] 



[ 



load" { name string } "; " ] 
import" name ";" ] 

module" name { [ "for" name ] [] } 

[ " import " import List ] [ ] } { [ "export " export List ] [ ] } " ; " 
end" "module" "; " ] 

-establish" name { [ "for" name ][]}";"] ( * reserved * ) 

-delete" name "; " ] (* reserved *) 

-save" name " ; " ] (* reserved *) 

-qualify" "; " ] (* reserved *) 



EOF } 

importList : : = 

{ [ name { [ "," importList ] [] } ] [] } 

exportList : : = 

{ [ typDecl { [ "," exportList ][]}][ procDecl { [ "," exportList ] [] } ] [] } 

typDecl : : = 

[ "type " name { typParams [ ] } "=" typ ] 



typ 



[ 



(" typList ")" { [ "->" typ ] [ "=>" typ ] [] } ] 
Option" typFields "end" ] 
{" typFields "}" ] 
[" { [ int "-*" ] [] } typ "] " ] 
All" "(" name { ["<:'* typ ] [] } " ) " typ ] 
Sortie" " ( " name { [ " < : " typ ] [ ] } " ) " typ ] 
Self" " (" name ") " typ ] 



[ name { [ "_" name { typParams [ ] } ] typParams [ ] } ] } 

typParams : := 

[ "(" typNameList ")" ] 

typNameList : : = 

{ [ name { [ ", " typList ][]}][]} 

typList : : = 

{ [ typ { [ ", " typList ][]}][]} 

typFields : : = 

{ [ name ":" typ { [ "," typFields ][]}][]} 

typSpec : : = 

{ [ ":" typ ] [] } 



typResSpec : : = 

{ [ ":" typ { [ "!" excList ] [] } ] [ "!" excList ] } 
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excList : : = 

{ [ name { [ "_" name ] } excList ] [ ] } 



procDecl : : = 

{ [ { "All" "Some" } "(" name { typBound [] } ")" procDecl ] 
[ name { [ ":" typ ] [ "(" ideList ")" typResSpec ][]}]} 

termBinding : := 

{ [ ide typSpec "=" term { [ " , " termBinding ] [ ] } ] [ ] } 

termSeq : : = 

[ term { [ ";" { termSeq []}][]}] 

termSeqOpt : : = 
{ termSeq [ ] } 

term : : = 

( termBase * 

{ [ " (" termList ") " ] 

[ "_" name { [ "(" termList ")" ] [] } ] 

[ "." name { [ ":=" termOrAlias ] [ "(" termList ")" ] [] } ] 
[ " :=" term ] 
[ " [ " term 

{["]"{[":=" term ] [] } ] 

[ "for" term "] " { [ ":=" term ][]}]}] 
[ ide term ] 
[ "andif " term ] 
[ "orif " term ] } ) 

termBase : : = 
{ 

[ " --" term ] 
ide 

{ "ok" "true" "false" char string int real } 
[ " [ " termList " ] " ] 

[ "{" { [ "protected" { "," []}][]}{[ "serialized" { "," []}][]} 

termOb jFields " } " ] 
[ "option" name typSpec "=>" termSeqOpt "end" 
[ "clone" " (" termList ") " ] 
[ "delegate" termSeq "to" termSeq "end" ] 
[ "proc" " ( " ideList " ) " { [ typResSpec " , " ] 
[ "meth" " ( " ideList " ) " { [ typResSpec " , " ] 
[ " (" termSeqOpt ") " ] 

[ "let" { [ "rec" termBinding ] termBinding } 
[ "var" { [ "rec" termBinding ] termBinding } 
[ "if" termSeq "then" termSeqOpt termElsif ] 
[ "case" termSeq "of" termCaseList ] 
[ "loop" termSeqOpt "end" ] 
"exit " 

[ "for" ide typSpec "=" term "to" term "do" termSeqOpt "end" ] 

[ " for each" ide typSpec "in" term { [ "do" termSeqOpt ] [ "map" termSeqOpt ] } "end" ] 
[ "exception" " (" term ") " ] 
[ "raise" " (" term ") " ] 
[ "try" termSeqOpt 

{ [ "except " termTryList "end" ] 

[ "else" termSeqOpt "end" ] 

[ "finally" termSeqOpt "end" ] } ] 
[ "lock" termSeq "do" termSeqOpt "end" ] 
[ "watch" termSeq "until" termSeq "end" ] 
[ "All" "(" name { [ "<:" typ ] [] } ")" term ] 
[ "Some" " ( " name { [ "< : " typ ] [ ] } " ) " term ] 
[ "Self" "(" name ")" term ] 

} 

termOrAlias : := 

{ term [ "alias " ide "of" termSeq "end" ] } 



[] } termSeqOpt "end" ] 
[ ] } termSeqOpt "end" ] 
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terraOb jFields : : = 

{ [ name typSpec "=>" termOrAlias { [ "," termOb jFields ] [] } ] [] } 



termElsif : := 
{ [ "end" ] 

[ "else" termSeqOpt "end" ] 

[ "elsif" termSeq "then" termSeqOpt termElsif ] } 

termList : : = 

{ [ term { [ ", " termList ][]}][]} 

ideList : : = 

{ [ ide typSpec { [ "," ideList ][]}][]} 

termCaseListEnd : := 

{ "end" [ "else " termSeqOpt "end" ] } 

termCaseList ::= 
{ termCaseListEnd 
[ name 

{ [ "(" ide typSpec ")" "=>" termSeqOpt { [ "," termCaseList ] termCaseListEnd } ] 
[ "=>" termSeqOpt { [ " , " termCaseList ] termCaseListEnd } ] } ] } 

termTryList : := 

{ [ "else" termSeqOpt ] 

[ term "=>" termSeqOpt { [ "," termTryList ] [ "else" termSeqOpt ] [] } ] 
[] } 
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B. System Reference 



This section contains information about running Obliq executables, handling source files, and us- 
ing built-in libraries. 



B.l The Executables 

The r obliq n Unix shell command is a script that runs one of several versions of Obliq linked with 
different Modula-3 libraries, providing different built-in Obliq libraries. Network capabilities are sup- 
ported in all versions of Obliq. 

Here are the executables currently provided, along with the supported built-in libraries: 

obliq -min (array, ascii, bool, int, math, net, real, sys, text) "minimal" obliq 

obliq -std (min + rd, wr, lex, fmt, pickle, process, thread) "standard" obliq 

obliq -ui (std + color, form) "windows" obliq 

obliq -anim (ui + graph, zeus) "animation" obliq 

By default, r obliq n means r obliq -std 1 . 

The reason for these separate versions is that the size of the binaries varies greatly depending on 
how many libraries are linked. The size affects linking time, startup-time, and paging behavior. 

A typical Obliq network server needs to be only an r obliq -min 1 or an r obliq -std 1 . An 
Obliq network client will often be an r obliq -ui 1 . 



B.2 TheTop-Level 

The "obliq 1 program, when executed, enters an interactive evaluation loop. At the prompt, r - \ 
the user can input a phrase, which is always terminated by a semicolon r ; n . The first phrase to try out is 
probably: 

- help; 

which provides basic on-line help on various aspects of the system. 

The most common kind of input phrase is a term phrase, which causes the parsing, evaluation, and 
printing of the result of an expression. Examples of term phrases (and comments) are: 

- 3+4; (* question *) 
7 (* answer *) 

- "this is" & " a single text"; (* text concatenation *) 
"this is a single text" 

- 3 is 4; (* identity test *) 
false 

Definition phrases are used to bind identifiers to values in the top-level scope. One can use var 1 
for binding values to updatable variables, "let 1 for binding values, including procedures, to constant 
identifiers, and r let ret for defining recursive procedures. 

- var x = 3; 
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- x : = x+1 ; 

- let y = x+1; 

- let rec fact = 

proc (n) 

if n is 0 then 1 else n * fact(n-l) end 
end; 

The Obliq top-level is statically scoped, just like the rest of the language. Hence, redefining an 
identifier at the top-level simply hides its previous incarnation and does not affect terms that already re- 
fer to it. 

When a top-level phrase finishes executing, the interpreter pretty-prints the result up to a small de- 
fault depth, printing ellipses after that depth. One can require a larger (but finite) print depth by insert- 
ing an exclamation mark before the final semicolon of a phrase; for example: r fact ! ; \ This larger 
default depth is sufficient in most situations. Otherwise, a given print depth r n" can be forced by saying 
r f act ! n; n . 

Closures are printed by printing their program text only. If there are global variables, these are in- 
dicated by "global ( xi, . . . , x n ) n followed by the program text. To print the values of global vari- 
ables, see r help flags;". 

B.3 Program Files 

Obliq programs should be stored in files with extension r . obi". Such files may contain any se- 
quence of top-level phrases. Files can then be loaded into the system, with the same effect as if they 
were typed in at the top-level. 

The top-level phrase: 

- load Foo; 

attempts to load the file r Foo . obl n along the current search path. Alternatively, one can use an explicit 
text string containing a file name (relative to the current search path), or an explicit file path: 

- load "Foo. obi"; 

- load " /udir/luca/Foo . obi " ; 

The search path for loading is set by the environment variable OBLIQPATH, and can be changed via 
the r sys n built-in library (see B.6.1, or r help sys; n ). 

At startup time, the Obliq system looks for a file called r . obliq in the user's HOME directory, 
and loads it if it finds it. 

B.4 Modules 

Obliq modules are used for: (1) organizing, loading, and reloading collections of definitions, and 
(2) for turning collections of definitions into libraries, so that qualified names can be used for the de- 
fined identifiers. Modules neither hide nor create scopes, except for turning identifiers into qualified 
identifiers when a module is closed. 

An Obliq source file should normally contain a single module. But, in general, multiple modules 
can be stored in the same file, and modules can also be entered directly at the top-level. Both the top- 
level and the source files may contain definitions that are not grouped into modules. 
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Modules can be used to record source file dependencies: when loading a module, the dependent 
modules are automatically loaded while avoiding duplicated loading. Modules also help keep the top- 
level consistent when reloading, for example after a bug fix. Reloading a module is like rolling back in 
time to the point when the module was first loaded: all intervening top-level definitions are discarded 
before the module is reloaded. 

It is recommended that a program file Foo . obi start with the line: 

module Foo; 
and end with the line: 

end module; 

A module named 'Foo 1 terminating with r end module; 1 is said to be closed. Closing Foo 1 
means erasing its definitions from the current scope, and adding back a library named 'Foo 1 containing 
those definitions. Hence, any top-level identifier 'x 1 declared within 'Foo 1 is accessible as r Foo_x 1 af- 
ter closing. (The syntax r m_x n is the same as for the built-in libraries.) 

If r end module ; 1 is omitted, the module is said to be open: its identifiers are accessible simply 
as 'x 1 . Closed modules should be the norm, but open modules are useful for importing definitions into 
the top level, and for allowing pervasive unqualified definitions. 

If a module 'Foo 1 relies on definitions stored in other program files (which should similarly start 
with 'module 1 lines), then 'Foo 1 can begin with the line: 

module Foo import Foo2,Foo3; 

The way the imported definitions are used within 'Foo 1 depends on whether the imported modules are 
open or closed. 

When issuing the top-level command 'load Foo ; n , the module declaration above guarantees two 
properties: (1) if the modules Foo2 and Foo3 have not been loaded already, they are loaded before 
Foo is loaded; (2) if the module Foo is already loaded, Foo and all the modules that were loaded after 
it are erased from the top level before reloading Foo. This roll-back affects only the top-level defini- 
tion environment: it does not undo state changes. 

The form 'module Foo for L ..- 1 indicates a collection of definitions named 'Foo 1 that gener- 
ates a library named 'L 1 (instead of the default 'Foo ) when the module is closed. Module names are 
unique at the top level (any repetition triggers roll-back), but library names can be repeated. When 
multiple modules generate the same library 'L 1 , their definitions are merged, with the latter ones taking 
precedence. Using this mechanism, it is possible to add definitions to built-in libraries, for example by 
'module text2 for text; 1 . 

B.5 The Network Objects Daemon 

A name server must be running before 'net_export 1 and similar operations can work. Obliq 
uses the name server provided with Modula-3 Network Objects [Birrell, et al. 1994], it can be started 
by the Unix command 'net ob j d 1 . 

To start a name server on your machine every time the Obliq interpreter starts, put the following 
line in the '. obliq 1 file in your home directory (make sure the 'net ob jd 1 path is appropriate): 

process_new (processor, [ " /pro j /mips/bin/netob jd" ] , true); 
The server process exits if it finds another copy of itself already running. 
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Note that objects and engines exported via the net 1 interface are not inherent security risks, even 
when they blindly execute client code. The operating system and file system of a server site are not 
necessarily available (see section A.2.9); lexical scoping prevents any unauthorized access. 



B.6 Built-in Libraries 

In this appendix we list the Obliq built-in libraries, many of which are entry points into popular 
Modula-3 libraries [Horning, et al. 1993]. We use an informal typing notation in the specification of 
the operations, including a specification of the exceptions that may be raised (see section A.4.1). Many 
operations raise errors as well, but these are not made explicit. 

We use the type comments of section A.4.1; all the exception conditions are documented, but the 
more obvious error conditions are not. We often provide informal English descriptions of the opera- 
tions. For details of some operations one should look at the specification of the respective Modula-3 
interfaces [Horning, et al. 1993]. 

The r sys n library is special: it contains entry points into the implementation of Obliq and its com- 
puting environment. 

B.6.1 Sys 



All ( T ) sy s_copy ( x : T) : T ! net_failure 

All ( T ) sy s_print ( x : T, depth: Int) : Ok 

sys _print Text (t : Text): Ok 
sys_printFlush ( ) : Ok 
sys_pushSilence ( ) : Ok 

sys_popSilence ( ) : Ok 

sys_setPrompt (first : Text, next: Text): Ok 

sys address : Text 
sys_getSearchPath ( ) : Text 

sys_setSearchPath (t : Text): Ok 

sys_getEnvVar (t : Text): Text 

sys_paramCount : Int 
sys_getParam(n: Int) : Text 
syscallFailure : Exception 

Some (T) Some (U) sys_call (name : Text, args : [T] ) : 



> (also r copy (x) ) Make a local copy of a value, including 
most distributed values. 

> Print an arbitrary value to stdout, up to some print depth. 
(Only available on-line.) 

> Print a text to stdout. (Only available on-line.) 

> Flush stdout. (Only available on-line.) 

> Push the silence stack; when non-empty nothing is printed. 
(Only available on-line.) 

> Pop the silence stack (no-op on empty stack). (Only avail- 
able on-line.) 

> Set the interactive prompts (defaults: first= "- 
next= " " ). (Only available on-line.) 

> The current machine's network address. 

> Get the current search path for r loacf and such. (Only 
available on-line.) 

> Set the current search path for r load n and such. (Only 
available on-line.) 

> Return the value of the env variable whose name is t, or 
r " " n if there is no such variable. 

> The number of program parameters. 

> Return the n-th program parameter (indexed from 0). 

> Can be raised by Modula-3 code during a sys_call. 
U ! sys_callFailure 

> Call a pre-registered Modula-3 procedure. 



B.6.2 Bool 



true : Bool 
false: Bool 

All (T) All (U)bool_is (x: T, y: U) : Bool 



All (T) All (D)bool_isnot (x: T, y: U) : Bool 
bool_not(b: Bool): Bool 
bool_and(bl: Bool, b2 : Bool): Bool 
bool_or(bl: Bool, b2 : Bool): Bool 



> The constant true. 

> The constant false. 

> (also infix r is ) Identity predicate: value equality for Ok, 
Bool, Int, Real, Char, Text, Exception; pointer equality 
otherwise. 

> (also infix r isnot n ) Negation of r is n . 

> (also r not (b) 1 ) 

> (also infix r and J 

> (also infix 'or) 
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B.6.3 Int 



n: Int 
~n: Int 

int_minus(n: Int) : Int 
int_+(nl: Int, n2 : Int): 
int_-(nl: Int, n2 : Int): 
int_*(nl: Int, n2 : Int): 
int_/(nl: Int, n2 : Int): 
int_%(nl: Int, n2 : Int): 
int_<(nl: Int, n2 : Int): 
int_>(nl: Int, n2 : Int): 
int_<=(nl: Int, n2 : Int) 
int_>=(nl: Int, n2 : Int) 



> 
> 
> 

Int > 
Int > 
Int > 
Int > 
Int > 
Bool > 
Bool > 
: Bool > 
: Bool > 



Positive integer constants. 
Negative integer constants. 
Integer negation. 
Integer addition. 
Integer difference. 
Integer multiplication. 
Integer division, 
(also infix % ) Integer modulo. 
Integer less-than predicate. 
Integer greater-than predicate. 
Integer no-greater-than predicate. 
Integer no-less-than predicate. 



B.6.4 Real 



n .m : 

~n.m 

real_ 

real_ 

real_ 

real_ 

real_ 

real_ 

real_ 

real_ 

real_ 

real_ 

real_ 

real_ 

real_ 

real_ 

real_ 

real_ 

real_ 

real_ 

real_ 

real_ 

real_ 

real_ 

real_ 

real_ 

real_ 

real_ 



Int 
; Int 

minus (n: Real) 
jninus (n : Int) : 



Real , n2 : 
Int, n2: 
Real , n2 : 
Int, n2: 
Real , n2 : 
Int, n2: 
Real, n2 : 
Int, n2: 
Real, n2 : 
Int, n2: 
Real, n2 : 
Int, n2: 
Real, n2 
Int, n2: 
Real, n2 
Int, n2: 
Int) : 
Real) : 
Real) : 
Int) : 
Real) : 
Int) : 



+ (nl 
+ (nl 
-(nl 
-(nl 

* (nl 

* (nl 
./(nl 
./(nl 
.< (nl 
.< (nl 

> (nl 

> (nl 
.<= (nl 
_<= (nl 

>= (nl 

>= (nl 
.float ( n : 

float (n: 

round ( n : 

round ( n : 

floor (n : 
.floor (n : 
.ceiling (n: Real 

ceiling (n: Int) 



Real 
Int 

Real) 
Int) : 

Real) 
Int) : 

Real) 
Int) : 

Real) 
Int) : 

Real) 
Int) : 

Real) 
Int) : 
: Real 

Int) : 
: Real 

Int) : 
Real 

Real 

Int 
Int 

Int 
Int 

) : Int 
: Int 



: Real 
Int 

: Real 
Int 

: Real 
Int 

: Real 
Int 

: Bool 
Bool 
: Bool 
Bool 
) : Bool 

Bool 
) : Bool 
Bool 



> Positive real constants; m is optional. 

> Negative real constants; m is optional. 

> (also -n ) Real negation. 

> (also -n ) Overloaded integer negation. 

> (also infix + ) Real addition. 

> (also infix r + ) Overloaded integer addition. 

> (also infix r - ) Real difference. 

> (also infix -) Overloaded integer difference. 

> (also infix * ) Real multiplication. 

> (also infix * ) Overloaded integer multiplication. 

> (also infix /) Real division. 

> (also infix V) Overloaded integer division. 

> (also infix r < ) Real less-than predicate 

> (also infix V) Overloaded integer less-than predicate 

> (also infix r > ) Real greater-than predicate 

> (also infix r > ) Overloaded integer greater-than predicate 

> (also infix r <= ) Real no-greater-than predicate 

> (also infix r <= ) Overloaded integer no-greater-than pred. 

> (also infix r >= ) Real no-less-than predicate. 

> (also infix r >= ) Overloaded integer no-less-than pred. 

> (also r f loat (n) n ) Integer-to-real conversion. 

> (also f loat (n) ) Overloaded; identity on reals. 

> (also round (n) ) Real-to-integer rounding. 

> (also 'round (n) ) Overloaded; identity on integers. 

> Greatest integers no greater than n. 

> Overloaded; identity on integers. 

> Least integers no less than n. 

> Overloaded; identity on integers. 



B.6.5 Math 



math_pi : Real 
math_e: Real 
math_degree : Real 

math_exp(n: Real) : Real 
math_log(n: Real): Real 
math_sqrt ( n : Real) : Real 
mathhypot ( n : Real, m: Real) : Real 
math_pow(n: Real, m: Real) : Real 
math_cos(n: Real) : Real 
math_sin(n: Real) : Real 
math_tan(n: Real) : Real 



> 3.1415926535897932384626433833. 

> 2.7 1 828 1 82845904523536028747 14. 

> 0.0 174532925 19943295769236907684; 
1 degree in radiants. 

> e to the n-th power. 

> log base e. 

> Square root. 

> sqrt((n*n)+(m*m)). 

> n to the m-th power. 

> Cosine in radians. 

> Sine in radians. 

> Tangent in radians. 
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math_acos(n: Real) : Real 

math asin (n : Real) : Real 

math_atan ( n : Real) : Real 

math_atan2 ( n : Real, m: Real) 



Real 



> Arc cosine in radians. 

> Arc sine in radians. 

> Arc tangent in radians. 

> Arc tangent of n/ra in radians. 



B.6.6 Ascii 



c: Char 

asciichar (n : Int) : Char 
ascii_val(c: Char): Int 



> A character in single quotes. 

> The ascii character of integer code V. 

> The integer code of the ascii character r c. 



B.6.7 Text 



t: Text 

text_new ( size : Int, init: Char) : Text 
text_empty (t : Text): Bool 
text_length (t : Text) : Int 
text_equal (tl : Text, t2 : Text): Bool 
text_char(t: Text, i: Int): Char 
text„sub(t: Text, start: Int, size: Int) 



text_S(tl: Text, t2: Text) 
text_precedes (tl : Text, t2 
text_decode (t : Text): Text 



: Text 

: Text) : Bool 



Text 



text_encode (t : Text): Text 

text_explode (seps : Text, t: Text): [Text] 



text_implode (sep: Char, a: [Text]): Text 



text_hash(t: Text) : Int 
text_toInt (t : Text): Int 
text„fromInt (n : Int): Text 

text_f indFirstChar ( c : Char, t: Text, n: Int) 



text_findLastChar (c : Char, t: Text, n: Int) 



text_findFirst (p: Text, t: 
text_f indLast (p : Text, t: 
text_replaceAll (old: Text, 



Int > 



Text, n: Int) 
Text, n: Int) : Int 
new: Text, t: Text) 



A string in double quotes. 
A text of size r size n , all filled with r init n . 
Test for empty text. 
Length of a text. 
Text equality (case sensitive). 

The i-th character of a text (if it exists); zero-indexed. 
The subtext beginning at start , and of size size (if it 
exists). 

> (also infix s ) The concatenation of two texts. 

> Whether 1 1 precedes 1 2 in lexicographic (ascii) order. 

> Every occurrence of an escape sequence is replaced by the 
corresponding non-printing formatting character: \\ = 
V; V n = r ' n ; r \' r = r,r ; r \n = Lf; \r= r CR\ 
r \t" = r Hf; r \f" = r Ff; \t" = "Hf; r \xxx = W 
(octals r 000\. r 177 n ); r \ c = "c 1 (otherwise). 

> Every occurrence of a non-printing formatting character is 
replaced by an escape sequence. 

> Splits an input text into a similarly ordered array of texts, 
each a maximal subsequence of the input text not contain- 
ing sep chars. The empty text is exploded as a singleton ar- 
ray of the empty text. Each sep char in the input produces a 
break, so the size of the result is 1 + the number of sep 
chars in the text, implode (explode ( 

" c " , text ) , ' c ' ) is the identity. 
net_f ailure 

> Concatenate an array of texts into a single text, separating 
the pieces by a single sep char. A zero-length array is im- 
ploded as the empty text, explode ( " c " , implode ( 

' c ' , text ) ) is the identity provided that the array has 
positive size and sep does not occur in the array elements. 

> A hash function. 

> Convert a text to an integer (see also fmt_). 

> Convert an integer to a text (see also lex_). 
Int 

> The index of the first occurrence of c in t , past n . - 1 
if not found. 

Int 

> The index of the last occurrence of "c" in t , before n . - 1 
if not found. 

The index of the first char of the first occurrence of p in 
'V, past V. -1 if not found. 

The index of the first char of the last occurrence of V m 
V, before V. -1 if not found. 

Text 

Replace all occurrences of r old n by new' in Y, as found 
by iterating r f indFirst^. 
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B.6.8 Array 



[e lf e n ] : [T] > (for el. . .en: T) 

All (T) array_new (size : Int, init: T) : [T] > An array of size 'size^, all filled with init. 

All (T) array„gen (size : Int, proc: (Int)->T): [T] 

> An array of size s i z e , filled with proc(i) for i 
between 'cf and'size-l^. 

All (T)array_# (a: [T] ) : Int ! net_failure > (also r # (a) n ) Size of an array. 

All (T)array_get (a: [T] , i: Int): T ! net_failure 

> (also 'a [ i T ) The i-th element (if it exists), zero-based. 
All (T)array_set (a: [T] , i: Int, b: T) : Ok ! net_failure 

> (also r a [ i ] : =b) Update the i-th element (if it exists). 
All(T)array_sub(a: [T] , i: Int, n: Int): [T] ! net_failure 

>(also'a[i for n] n ) A new array, filled with the ele- 
ments of 'a^ beginning at i , and of size n (if it exists). 
All (T)array_upd(a: [T] , i: Int, n: Int, b: [T] ) : Ok ! net_failure 

>(also'a[i for n]:=b n ) Same as 'a [n+i] :=b [n] ; 
... ; a[i] :=b[0f.I.e.'a[i for nfgets'b[0 
for n] . 

All (T)array_@ (al : [T] , a2 : [T] ) : [T] ! net_failure 

> (also infix '(f) A new array, filled with the concatenation 
of the elements of 'al n and 'a2 n . 

B.6.9 Net 

net_f allure: Exception 

All (T) net__who (o : T) : Text ! net_failure thread_alerted 

> Return a text indicating where a network object or engine 
is registered, or the empty text if the argument is an object 
that has not been registered with a name server. 

All (T< :{}) net_export (name : Text, server: Text, o: T): T ! net_failure thread_alerted 

> Export an object under name name', to the name server at 
IP address 'server. The empty text denotes the local IP 
address. 

Some (T< :{}) net_import (name : Text, server: Text): T ! net„failure thread_alerted 

> Import the object of name 'name , from the name server at 
IP address 'server . The empty text denotes the local IP 
address. 

All (T) net_exportEngine (name : Text, server: Text, arg: T) : Ok 

! net_failure thread_alerted 

> Export an engine under name name , to the name server at 
IP address server . The empty text denotes the local IP 
address. The arg is given as an argument to all proce- 
dures received by the engine to execute. 

Some (T) All (U) net_importEngine (name : Text, server: Text): ( (T) ->U) ->U 

! net_failure thread_alerted 

> Import the object of name name , from the name server at 
IP address 'server . The empty text denotes the local IP 
address. 

B.6.10 Thread 

threadjnutex ( ) : Mutex > (also 'mutex ( ) n ) A new mutex. 

thread_condition ( ) : Condition > (also 'condition () n ) A new condition. 

Some (T) thread_self ( ) : Thread (T) > The current thread. 

All (T) thread_fork (f : ()->T, stackSize: Int): Thread(T) 

> (also fork(f,n) ) Fork a new thread executing f. If 
stackSize is zero, a small default size is used. 

All (T) thread_join (th : Thread(T)): T > (also 'join (th) ~) Wait for a thread to complete, and re- 

turn the result of its procedure. 
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thread_wait (mx : Mutex, cd: Condition): Ok > (also Wit (mx, cd) ) Wait on a mutex and a condition. 

thread_acquire (mx : Mutex): Ok > Acquire a mutex (use lock ... end instead). 

thread_release (mx : Mutex): Ok > Release a mutex (use lock ... end instead) 

threadjsroadcast (cd: Condition): Ok > (also broadcast ( cd) n ) Wake-up to all threads waiting 

on a condition. 

thread_signal (cd: Condition): Ok > (also Signal (cd) n ) Wake-up at least one thread waiting 

on a condition. 

thread_pause ( r : Real) : Ok > (also pause (r) ) Pause the current thread for r seconds. 

All (T) thread_lock (m : Mutex, body: ()->T): T > Execute under a locked mutex (use lock ... end instead), 
thread alerted: Exception > (See the threads spec.) 

All (T) thread_alert (t : Thread (T) ) : Ok > (See the threads spec.) 

threadtestAlert ( ) : Bool > (See the threads spec.) 

thread alertWait (mx : Mutex, cd: Condition) : Ok ! thread_alerted 

> (See the threads spec.) 
All (T) thread_alert Join (th: Thread(T)): Ok ! thread_alerted 

> (See the threads spec.) 
thread_alertPause ( r : Real): Ok ! thread_alerted 

> (See the threads spec.) 



B.6.11 Rd 



rd_failure: Exception 
rd eofFailure : Exception 

rd_new(t: Text): Rd > A reader on a text (a Modula-3 TextRd). 

rd_stdin : Rd > The standard input (the Modula-3 Stdio.Stdin). 

rd open(fs: FileSystem, t: Text): Rd ! rd_failure 

> Given a file system and a file name, returns a reader on a 
file (a Modula-3 FileRd, open for read). The local file sys- 
tem is available through the predefined lexically scoped 
identifier f ileSys . Moreover, f ileSysReader is a 
read-only version of the local file system. 

rd_getChar ( r : Rd) : Char ! rd_failure rd_eof Failure thread_alerted 

> Get the next character from a reader. 
rd_eof(r: Rd) : Bool ! rd_failure thread_alerted 

> Test for the end-of-stream on a reader. 
rd_unGetChar ( r : Rd) : Ok > Put the last character obtained by getChar back into the 

reader (unfortunately, it may crash if misused!). 
rd_charsReady ( r : Rd) : Int ! rd_failure > The number of characters that can be read without block- 

ing. 

rd_getText ( r : Rd, n: Int): Text ! rd_failure thread_alerted 

> Read the next n characters, or at most n on end-of-file. 
rd getLine ( r : Rd) : Text ! rd_failure rd_eof Failure thread_alerted 

> Read the next line and return it without including the end- 
of-line character. 

rd_index(r: Rd) : Int > The current reader position. 

rd_length(r: Rd) : Int ! rd_failure thread_alerted 

> Length of a reader (including read part). 
rd_seek(r: Rd, n: Int) : Ok ! rd_failure thread_alerted 

> Reposition a reader. 
rd_close(r: Rd) : Ok ! rd_failure thread_alerted 

> Close a reader. 

rd intermittent ( r : Rd) : Bool > Whether the reader is stream-like (not file-like). 

rd_seekable ( r : Rd) : Bool > Whether the reader can be repositioned. 

rd_closed(r: Rd) : Bool > Whether the reader is closed. 



B.6.12 Wr 



wr_failure: Exception 
wr_new ( ) : Wr 
wr_toText(w: Wr) : Text 
wrstdout : Wr 



> A writer to a text (a Modula-3 TextWr). 

> Emptying a writer to a text.. 

> The standard output (the Modula-3 Stdio.Stdout). 
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wr_stderr : Wr > The standard error (the Modula-3 Stdio.Stderr). 

wr open(fs: FileSystem, t: Text): Wr ! wr_failure 

> Given a file system and a file name, returns a writer to the 
beginning of a file (a Modula-3 FileWr, open for write). 
The local file system is available through the predefined 
lexically scoped identifier r f ileSys^. 

wr openAppend ( f s : FileSystem, t: Text) : Wr ! wr_failure 

> Given a file system and a file name, returns a writer to the 
end of file (a Modula-3 FileWr, open for append). The lo- 
cal file system is available through the predefined lexically 
scoped identifier fileSys . 

wr_putChar (w : Wr, c: Char) : Ok ! wr_failure thread„alerted 

> Put a character to a writer . 
wr_putText (w : Wr, t: Text) : Ok ! wr_failure thread_alerted 

> Put a text to a writer . 
wr_flush(w: Wr) : Ok ! wr_f ailure thread_alerted 

> Flush a writer: all buffered writes to their final destination. 
wr_index(w: Wr) : Int > The current writer position 

wr_length(w: Wr) : Int ! wr_failure thread„alerted 

> Length of a writer. 
wr_seek(w: Wr, n: Int) : Ok ! wr_failure thread_alerted 

> Reposition a writer. 
wr„close(w: Wr) : Ok ! wr_f ailure thread_alerted 

> Close a writer. 

wr_buffered(w: Wr) : Bool > Whether the writer is buffered. 

wr_seekable (w: Wr) : Bool > Whether the writer can be repositioned. 

wr_closed(w: Wr) : Bool > Whether the writer is closed. 

B.6.13 Pickle 

pickle_f ailure : Exception 

All (T) pickle_write (w : Wr, v: T) : Ok ! pickle„f ailure wr_failure thread_alerted 

> Copy a value to a writer, similarly to sys_copy. 
Some (T) pickle_read (r : Rd) : T ! pickle_f ailure rd_failure rd_eof Failure thread_alerted 

> Copy a value from a reader, similarly to sys_copy. 

B.6.14 Lex 

lex_f ailure: Exception 

lex_scan(r: Rd, t: Text) : Text ! rd_failure thread_alerted 

> Read from r the longest prefix formed of characters listed 
in t, and return it. 

lex_skip(r: Rd, t: Text) : Ok ! rd_failure thread_alerted 

> Read from r the longest prefix formed of characters listed 
in t, and discard it. 

lex_match(r: Rd, t: Text) : Ok ! lex_failure rd_failure thread_alerted 

> Read from r the string t and discard it; raise failure if not 
found. 

lex_bool(r: Rd) : Bool ! lex_failure rd_failure thread_alerted 

> Skip blanks, and attempt to read a boolean from r. 
lex_int(r: Rd) : Int ! lex_f ailure rd_f ailure thread_alerted 

> Skip blanks, and attempt to read an integer from r. 
lex_real(r: Rd) : Real ! lex_f ailure rd_f ailure thread_alerted 

> Skip blanks, and attempt to read a real from r. 

B.6.15 Fmt 

fmt_padLft (t : Text, length: Int): Text > If t is shorted then length, pad t with blanks on the left so 

that it has the given length. 
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fmt_padRht (t : Text, length: Int) : Text 

fmt_bool(b: Bool): Text 
fmt_int(n: Int): Text 
fmt_real(r: Real): Text 



> If t is shorted then length, pad t with blanks on the right so 
that it has the given length. 

> Convert a boolean to its printable form. 

> Convert an integer to its printable form. 

> Convert a real to its printable form. 



B.6.16 Process 



process new (pr : Processor, nameAndArgs : [Text], mergeOut: Bool) : Process 

> Create a process from a processor and the given process 
name and arguments. The local processor is available as 
the lexically scoped identifier r processor n . If mergeOut 
is true, use a single pipe for stdout and stderr. 

Wr > The stdin pipe of a process. 

Rd > The stdout pipe of a process. 

Rd > The stderr pipe of a process. 

: Int > Wait for the process to exit, close all its pipes, and return 

the exit code. 

process f liter (pr : Processor, nameAndArgs: [Text], input: Text) : Text ! net_failure 

> Create a process from a processor and the given process 
name and arguments. The local processor is available as 
the lexically scoped identifier processor . The stderr 
output is merged stdout. Usage: feed the input to its stdin 
pipe and close it; read all the output from its stdout pipe 
and close it; return the output. 



process 
process 
process 
process 



_in (p : Process) : 
_out (p: Process) : 
err (p : Process) : 
_wait(p: Process) 



B.6.17 Color 



color_named (name : Text) : Color 

color_rgb ( r : Real, g: Real b: Real): Color 

color_hsv(h: Real, s: Real v: Real) : Color 

color_r(c: Color): Real 

color__g(c: Color): Real 

color_b(c: Color): Real 

color_h(c: Color): Real 

color_s(c: Color): Real 

color_v(c: Color): Real 

color_brightness (c : Color): Real 



> Get a color from its name (see the ColorName Modula-3 
interface). 

> Get a color from rgb (each 0.0 .. 1.0). 

> Get a color from hsv (each 0.0 .. 1.0). 

> The red color component. 

> The green color component. 

> The blue color component. 

> The hue color component. 

> The saturation color component. 

> The value color component. 

> The total brightness (0.0 .. 1.0). 



B.6.18 Form 



f orm f ailure : Exception 

form_new(t: Text): Form ! form_f ailure > Read a form description from a text, 

f orm„f romFile ( f ile : Text) : Form ! form_f ailure thread_alerted 

> Read a form description from a file, 
f orm_attach ( f v : Form, name: Text, f: (Form)->Ok) : Ok ! form_failure 

> Attach a procedure to an event, under a form. The proce- 
dure is passed back the form when the event happens. 

f orm getBool ( f v : Form, name: Text, property: Text) : Bool ! form_failure 

> Get the boolean value of the named property of the named 
interactor. (Do not confuse with form„getBoolean.) 

f orm_putBool ( f v : Form, name: Text, property: Text, b: Bool) : Ok ! form_failure 

> Set the boolean value of the named property of the named 
interactor. (Do not confuse with form_putBoolean.) 

f orm_getInt ( f v : Form, name: Text, property: Text): Int ! form_failure 

> Get the integer value of the named property of the named 
interactor. If property is the empty text, get the r "value" n 
property. 
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f ormjputlnt ( f v : Form, name: Text, property: Text, n: Int) : Ok ! form_failure 

> Set the integer value of the named property of the named 
interactor. If property is the empty text, set the ^'value"" 1 
property. 

f ormgetText ( f v : Form, name: Text, property: Text) : Text ! form_failure 

> Get the text value of the named property of the named in- 
teractor. If property is the empty text, get the r " value" n 
property. 

f orm_putText ( f v : Form, name: Text, property: Text, t: Text, append: Bool) : Ok ! 

f orm_f ailure 

> Set the text value of the named property of the named in- 
teractor. If property is the empty text, set the r "value' p 
property. 

f orm_getBoolean ( f v : Form, name: Text) : Bool ! form_failure 

> Get the boolean value of the named boolean-choice inter- 
actor. 

f orm_putBoolean ( f v : Form, name: Text, b: Bool) : Ok ! form_f ailure 

> Set the boolean value of the named boolean-choice interac- 
tor. 

f ornLgetChoice (fv : Form, radioName: Text): Text ! form_failure 

> Get the choice value of the named radio interactor. 
form_putChoice (fv : Form, radioName: Text, choiceName: Text) : Ok ! form_failure 

> Set the choice value of the named radio interactor. 
f orm_getReactivity ( f v : Form, name: Text) : Text ! form_f ailure 

> Get the reactivity of the named interactor. It can be 
r "active""", '""passive""', r "dormant' p , or ^'vanished" 1 . 

f orm_putReactivity ( f v : Form, name: Text, r: Text) : Ok ! form_failure 

> Set the reactivity of the named interactor. It can be 
r "active"\ '""passive" 1 , r "dormant" n , or ^'vanished"" 1 . 

f orm_popUp ( f v : Form, name: Text): Ok ! form_failure 

> Pop up the named interactor. 
f orm_popDown ( f v : Form, name: Text) : Ok ! form_failure 

> Pop down the named interactor. 
f orm_insert ( f v : Form, parent: Text, t: Text, n: Int) : Ok ! form_failure 

> Insert the form described by t as child n of parent, 
f ormjnove ( f v : Form, parent: Text, child: Text, toChild: Text, before: Bool) : Ok ! 

form_f ailure 

> Move child before or after toChild of parent; after "" 
means first, before "" means last. 

f ormdelete ( f v : Form, parent: Text, child: Text) : Ok ! form_f ailure 

> Delete the named child of parent. 

f orm_deleteRange ( f v : Form, parent: Text, n: Int, count: Int): Ok ! form_failure 

> Delete count children of parent, from child n. 
f orm_takeFocus (fv : Form, name: Text, select: Bool) : Ok ! form_failure 

> Make the named interactor acquire the keyboard focus, and 
optionally select its entire text contents. 

f ornushow ( f v : Form): Ok ! form_f ailure > Show a window containing the form on the default display, 

f orm_showAt ( f v : Form, at: Text, title: Text) : Ok ! form_f ailure 

> Show a window containing the form on a display. For an X 
display: at= "machineName(':'\'::')num("\\'num)" ; at= "" 
is the default display. The title is shown in the window 
header. 

f ormjiide ( f v : Form): Ok ! form„f ailure > Hide the window containing the form. 
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C. Programming Reference 

In this section we provide information useful to programmers who want to call Obliq from Mod- 
ula-3, or vice versa. 

C.l The Package Hierarchy 

One of our goals is that Obliq should be easily embeddable in Modula-3 applications. Obliq adds 
only a small size overhead to typical Modula-3 applications, but we still want to minimize this over- 
head. To this end, the Obliq implementation is partitioned into several packages, with a Modula-3 li- 
brary in each package, so that each application can link only the appropriate libraries. Another advan- 
tage of this organization, is that we can generate minimal Obliq interpreters that can act as (relatively) 
small network servers. 

Here is the package structure. Each node is a package (a collection of interfaces), which uses the 
connected packages above it. The nodes in italic represent packages external to the Obliq implementa- 
tion. 



Each package has a principal interface; that interface contains a r PackageSetup ( ) n routine that 
must be called at least once to initialize all the modules in the package. 

The r obliqrf package implements the Obliq run-time kernel, which is the smallest part of Obliq 
that can be usefully embedded in an application. Note that this does not include parsers and printers; 
these are separately provided in r obliqparse n and r obliqprinf . 

The r obliq n package brings together everything needed to build stand-alone Obliq interpreters. This 
package can be linked with various library packages to produce various flavors of Obliq interpreters. 

Each underlined package contains a short Main program and a binary for an interpreter ( r -bin- ) or 
a server ( r -srv- n ). 

Modula-3 programmers can extend the hierarchy along the dotted lines. 



synloc 




obliqbinanim 
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C.2 The Interfaces 



The main client interface is r obliqrt/src/Obliq.i3 n , which refers to r obliqrt/src/ObTree.i3 n (the parse 
trees) and r obliqrt/src/ObValue.i3 n (the run-time values). r Obliq.i3 n contains: routines to create and in- 
spect Obliq values (including operations on remote objects), exceptions, and errors; "Eval" routines for 
Obliq parse trees; and r sys_call n registration to invoke Modula-3 routines from Obliq. 

The Obliq parser and printer are separate from the run-time, and need not be linked into an appli- 
cation, since an application may access evaluated objects and closures over the network. The main in- 
terface to the parser is r obliqparse/src/ObliqParser.i3 n , which contains routines to parse and evaluate 
Obliq phrases from a reader. The interface gives an example of a simple read-eval loop. The main in- 
terface to the printer, which performs pretty-printing, is r obliqprint/src/ObliqPrinter.i3 n . 



C.3 The Libraries 

Every Obliq client must link with libobliqrt . The parser is in r libobliqparse n , and the printer is in 
libobliqprint". For building interpreters, link with r libobliq n . 

In every case, one must include whatever libraries are needed to get the desired Obliq built-in 
packages and features, as described below: 

libobliqrt: array, ascii, bool, int, math, net, real, sys, text 

libobliq: sys on-line extensions, on-line help 

libobliqlibm3: rd, wr, lex, fmt, pickle, process, thread 

libobliqlibui: color, form 

libobliqlibanim: graph, zeus 



C.4 Embedding Obliq in an Application 

The appropriate client interfaces are r obliqrt/src/Obliq.i3 n , r obliqparse/src/ObliqParser.i3"', and 
r obliqprint/src/ObliqPrinter.i3^. 

One may have to refer to other interfaces as well, particularly r ObTree.i3 n (the parser trees) and 
r ObValue.i3 n (the run-time values). Note though that r ObTree.i3 n is particularly specific to the current 
Obliq implementation, and should be used as "abstractly" as possible; the r ObliqParser.i3 n interface 
should isolate clients from any such dependencies. r ObValue.i3 n is also likely to evolve over time; most 
of its facilities can be accessed safely from r Obliq.i3 n . 

The Obliq evaluator takes as arguments a syntax tree, and an environment. The environment, 
mapping identifiers to Obliq values, is particularly important. By manipulating the environment, one 
can submit values to Obliq for evaluation, and can recover the results of an evaluation. 

C.5 Extending Obliq with sys_calls 

A r sys_call n is a cheap way of extending the functionality of an Obliq interpeter with a new 
"built-in" operation that invokes Modula-3 code. For more ambitious extensions, see section C.6. 

The interface r obliqrt/src/Obliq.i3 n describes how to register a Modula-3 procedure so that it can be 
invoked from Obliq. For a procedure registered under the name r " f o o " \ the Obliq syntax is: 

sys_call ( " f oo" , [arg lf arg n ] ) 

The interface r obliqrt/src/ObLib.i3 n contains examples of how to analyze the argument array passed 
by Obliq to Modula-3. 
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One must then link the Modula-3 code implementing r f oo 1 with Obliq, either in an application 
(section C.4) or in a custom interpreter (section C.7). 

C.6 Extending Obliq with new Packages 

The interface r obliqrt/src/ObLib.i3 n can be used to add a new built-in package to Obliq. One can 
extend Obliq with new built-in types, exceptions, and operations. All the built-in Obliq packages are 
implemented through this interface. 

The interface contains a detailed example of how to write and register such a package. 

C.7 Building a Customized Obliq Interpreter 

A new package, created as described in section C.6, can be embedded into a customized Obliq in- 
terpreter. Follow the example given by r obliqbinstd/src/Main.m3 n : this is the 20-line program that 
builds the standard Obliq interpreter. The other r obliqbin.../src/Main.m3 n files contain other versions of 
the interpreter. 
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